SeasarJavadocProject の履歴(No.56)

Seasar Java プロダクトの Javadoc を書こう†

Seasar Javadoc Project は，Seasar2 を始めとする Java プロダクトに Javadoc コメントを記述していくプロジェクトです．
Seasar Javadoc Project にはどなたでも参加できます．
協力して頂ける方を募集しています．実行力のある方大歓迎！！

↑

参加手順†

seasar-javadoc ML にて参加表明してください．

seasar.org のアカウントを持っていない人は参加表明に以下のフォームでアカウントの申請を記述してください．

氏名・ハンドルネーム:
連絡先メールアドレス: (スパムロボットに収集されないように改変可能)
ブログ／ホームページのURL： (もしあれば)
希望アカウント名
　第一希望: ( svnでSeasar.orgにcommit
　第二希望:                    する時のアカウント )

↑

Javadoc の生成手順†

↑

Maven2 のインストール†

Javadoc の生成は Maven2 で行います． Maven2 は以下からダウンロードすることができます (インストール手順というか設定もあります)．

http://maven.apache.org/download.html#installation

↑

Seasar2 のチェックアウト†

Eclipse で SVN からチェックアウトします． Seasar2 のリポジトリの URL は以下です．

https://www.seasar.org/svn/s2container/

Javadoc の記述は trunk で行います． trunk/seasar2 をチェックアウトしてください．

↑

Javadoc の生成†

コマンドプロンプトを開いて seasar2 ディレクトリへ移動します．
次のコマンドを実行します．

mvn javadoc:javadoc

seasar2/s2-framework/target/site/apidocs ディレクトリに Javadoc が生成されます．

↑

作業手順†

対象となるパッケージの決定
Javadoc コメントは参加者全員が1つのパッケージに集中して作業していきます．対象となるパッケージは seasar-javadoc ML にて決定します．

サインアップ
参加者は担当するクラスを決定し，サインアップ一覧の担当者名にアカウント名，開始日欄にサインアップした日付を記入します．
担当するクラスは一度に多く取りすぎないようにしてください (未完了のクラス == 在庫を増やさないようにするため)．
担当する未完了のクラス数は原則として上限を 5 クラスとします．

フォーマット
Eclipse でソースコードをフォーマットします．
フォーマットするにはエディタで担当のクラスを開いて Ctrl+Shift+F を押下します．パッケージ・エクスプローラ等のビューで変更のマーカ (デフォルトでは '*') が表示された場合は SVN にコミットします．その際のコミットログは
```
formatted.
```
と入力してください．

Javadoc の記述
ソースコードに Javadoc を記述してください．
ソースファイルを保存する際は同時にフォーマット (Ctrl+Shift+F) してください．次の Eclipse プラグインを使用すると保存と同時にフォーマットされて便利です．
http://sourceforge.net/project/showfiles.php?group_id=47272&package_id=164404

Javadoc の確認
Javadocを生成して「リンク切れ」や「レイアウトの崩れ」がないかブラウザで確認してください．

ML でレビュー
Javadoc を記述したソースを添付して seasar-javadoc ML へ投稿してください．他のメンバーから指摘された点について議論・修正を行って再度投稿をしてください．

コミット
1 名以上の開発担当コミッタから承認があり，他のメンバーから指摘がなければ SVN にコミットします．その際のコミットログは
```
added Javadoc comment.
```
としてください．一度コミットした後，Javadoc コメントを修正した場合のコミットログは
```
modified Javadoc comment.
```
としてください．

終了日の入力
Javadoc コメントのコミットが完了したクラスについて，サインアップの終了日にその日付，レビュー欄に承認した開発担当コミッタのアカウント名を入力してください．

問題がなければサインアップのレビュー欄にコミッタの名前を入力します．

完了
パッケージ内の全てのクラスのレビューが終了したら完了となり，次のパッケージの作業を開始します．

↑

サインアップ†

クラス	担当	開始日	終了日	レビュー
AbstractAnnotationHandler.java
AbstractS2ContainerBuilder.java	belltree	2006/11/28
AbstractTagHandler.java
AnnotationHandler.java
AnnotationHandlerFactory.java
ArgTagHandler.java	−	−	−	−
AspectDefFactory.java
AspectTagHandler.java	−	−	−	−
CircularIncludeRuntimeException.java
ClassPathResourceResolver.java
ComponentsTagHandler.java	−	−	−	−
ComponentTagHandler.java	−	−	−	−
ConstantAnnotationHandler.java
DestroyMethodTagHandler.java	−	−	−	−
DICapableClassLoader.java
IncludeTagHandler.java	−	−	−	−
InitMethodTagHandler.java	−	−	−	−
InterTypeTagHandler.java	−	−	−	−
MetaTagHandler.java	−	−	−	−
MethodTagHandler.java	−	−	−	−
PathResolver.java
PropertyTagHandler.java	−	−	−	−
ResourceResolver.java
S2ContainerBuilder.java	azusa	2006/12/12
S2ContainerFactory.java	jundu	2006/11/21
S2ContainerTagHandlerRule.java
SimplePathResolver.java
SingletonS2ContainerFactory.java	goto	2006/12/02
TagAttributeNotDefinedRuntimeException.java
WebResourceResolver.java
XmlS2ContainerBuilder.java
package.html

↑

方針†

private には書かない
S2 の利用者が直接使いそうなものから書いていく
@see の先が出来る前でも @see をとりあえず書いておく
Javadoc は仕様を書くもの
実装者の視点ではなく，利用者の視点で読めるように書く
HTML (HTML 4.01 Transitional を想定) で書く

↑

表記†

SUN に合わせて「ですます調」で
句読点は「、。」で
英数は1byte文字で。2bytes文字との間に空白を入れない。
数字は(いわゆる)半角に統一
カタカナは(いわゆる)全角に統一
機種依存文字は使用禁止

↑

表記がブレそうな言葉を統一†

日本語と横文字
○ ×

パフォーマンス性能

レコード行

カラム列

テーブル表

インデックス索引

主キープライマリキー

○	×
パフォーマンス	性能
レコード	行
カラム	列
テーブル	表
インデックス	索引
主キー	プライマリキー

横文字

○	×
ユーザ	ユーザー
インターフェース	インタフェース
クラスローダ	クラスローダー
ファクトリ	ファクトリー
インターセプタ	インターセプター
コンフィギュレーション?	コンフィグレーション?
ビルダ? ビルダー?	?

ひらがなと漢字

○	×
ください	下さい
..の方	..のほう
既に	すでに
主な(に)	おもな(に)
出来ます	できます
良い	よい
など	等
例えば	たとえば
そのとおり	その通り
行なう	行う

漢字と数字
○ ×

1つ一つ

○	×
1つ	一つ

英語
○ ×

Web WEB、ウェブ

○	×
Web	WEB、ウェブ

getterとsetter
- ○ ×

getter 〜を返します〜を取得します

setter 〜を設定します〜をセットします

-	○	×
getter	〜を返します	〜を取得します
setter	〜を設定します	〜をセットします

JavaEE用語
○ × 意味

Webコンテナサーブレットコンテナ, Servletエンジン TomcatなどのServlet実行環境

○	×	意味
Webコンテナ	サーブレットコンテナ, Servletエンジン	TomcatなどのServlet実行環境

Seasar用語

○	×	意味
S2コンテナ	コンテナ, DIコンテナ	Seasar2のDIコンテナ、"S2Container"のインスタンス
インジェクションする	DIする, 割り当てる, Injectionする	依存性注入(Dependency Injection)を行う

文中で使用するクラスやインターフェースの日本語名

org.seasar.framework.container

クラス/インターフェース名	日本語名	説明
AccessTypeDef	アクセスタイプ定義
AspectDef	アスペクト定義
AutoBindingDef	自動バインディング定義
BindingTypeDef	バインディングタイプ定義
ComponentDef	コンポーネント定義
ComponentDeployer	コンポーネントデプロイヤ
DestroyMethod	?
Expression	式?
ExternalContext	外部コンテキスト
ExternalContextComponentDef	外部コンテキストコンポーネント定義
InitMethodDef	初期化メソッド定義
InstanceDef	インスタンス定義
InterTypeDef	?
MetaDef	メタデータ定義
MethodDef	メソッド定義
PropertyDef	プロパティ定義
S2Container	S2コンテナ

↑

HTMLタグの使い方を統一†

順引き

<code>〜</code> (一部 {@link 〜} を含む)

キーワード(予約語)

A	abstract	assert
B	boolean	break	byte
C	case	catch	char	class	const	continue
D	default	do	double
E	else	enum*	extends
F	final	finally	float	for
G	goto
I	if	implements	import	instanceof	int	interface
L	long
N	native	new
P	package	private	protected	public
R	return
S	short	static	strictfp	super	switch	synchronized
T	this	throw	throws	transient	try
V	void	volatile
W	while

識別子

識別子	例
インターフェース名	{@link InterfaceName}
クラス名	{@link ClassName}
メソッド名	{@link #methodName} または {@link #methodName(String)}
フィールド名	{@link #instanceField}, {@link #classField}
変数名	<code>localVariable</code>, <code>parameter</code>

リテラル
種類例

null値 <code>null</code>

boolean値 <code>true</code>, <code>false</code>

数値 <code>3.14159265358979</code>(円周率の意味で)

文字列 <code>"HOGE"</code>

種類	例
null値	<code>null</code>
boolean値	<code>true</code>, <code>false</code>
数値	<code>3.14159265358979</code>(円周率の意味で)
文字列	<code>"HOGE"</code>

Seasar関係
種類例

diconファイルのタグ名 <code>component</code>タグの…

diconファイルの属性名 <code>instance</code>属性で…

種類	例
diconファイルのタグ名	<code>component</code>タグの…
diconファイルの属性名	<code>instance</code>属性で…

逆引き

良くない例

↑

その他†

説明文の記述パターン
記述内容例

デフォルト値の記述 <dt>singleton (default)</dt>？

定数値を返すメソッドの記述コンポーネント定義の文字列表現を返します。

記述内容	例
デフォルト値の記述	<dt>singleton (default)</dt>？
定数値を返すメソッドの記述	コンポーネント定義の文字列表現を返します。

文字参照
- 「@」はJavadoc上特殊な文字なので、「@」を特別な意味を持たない文字として記述する場合は文字参照を使用します。
  コメントの先頭や中括弧「{}」の先頭に「@」がある場合にのみ「@」は特殊な働きをしますが、このようにしておけば「@」の記述位置を気にする必要がなくなります。
- HTMLでの「"」「&」「<」「>」
  @ @
  
  " "
  
  & &
  
  < <
  
  > >

@authorに自分の名前を追記するとき
- ~~Javadocに自分の名前を追記するときは、名前の後に(Javadoc)を追記します~~。 (JavaDoc)の追加はしないことになりました。
@throwsの記述方針
- インターフェースで例外を記述するときは、実装クラス側でスローする可能性のある例外をすべて記述します。
@linkと<code>の使い分け
- @linkと<code>は併用しません。@linkだけでOK。
修飾名と非修飾名
- 同じパッケージに属するクラスを記述する場合、修飾名で書かなくても良いです。クラス名だけでOK。
戻り値がbooleanのメソッドの @return の記述
@return 〜の場合<code>true</code>

↑

レイアウトに関する工夫†

フォーマット(Ctrl+Shift+F)時に、なるべく句読点の位置で改行させる工夫
- 読点(、) の後ろには (いわゆる) 半角スペースを入れる．
- 句点(。) の後ろでは改行する．

↑

Javadoc よりも他のドキュメントが良い場所†

interceptors
- これは Javadoc あった方がよいのでは？
継承して使うことがある場所
- ResultSetHandler

↑

Eclipse Tips†

↑

Javadoc の生成†

クラスまたはメソッドを選んで右クリック「ソース」−「コメントの追加」(ショートカットは Ctrl+Shift+J)．

↑

インタフェースを実装したクラスを開く†

Java エディタでインタフェースを開いている時に Ctrl+T で実装クラスがポップアップ表示されエディタで開くことができます．

↑

Eclipse で Javadoc を扱う便利な方法†

　ソースコードを追う時には Javadoc は邪魔なんじゃい！ヽ(`Д´)ﾉ
という方。Eclipse をご利用であれば、設定の [Java]-[エディター] のフォールディングタブを開いてください。それから「コメント」をチェック。次から開くソースコードはデフォルトでコメントが折りたたまれています。
　また、Eclipse で Javadoc を参照するのに便利な方法が二つあります。
　一つは Javadoc ビューを開くこと。キャレット (カーソル) がある位置の Javadoc の内容が、HTML レンダリングされて Javadoc ビューに表示されます。
　もう一つは、[Java]-[エディター] の吹き出しタブで「Javadoc」にチェックを入れてください。修飾キーに適当なもの (Alt とか) を設定しましょう。その修飾キーを押しながらメソッド名などをポイントすることで HTML レンダリングされた Javadoc が表示されるようになります。

↑

ファイルを保存と同時にフォーマットしてくれるプラグイン†

http://sourceforge.net/project/showfiles.php?group_id=47272&package_id=164404

更新サイトはhttp://ejp.sourceforge.net/formatonsave/update/です。

メニューの「Window」−「Preferences」から「Java」−「Format on save」を選んで

「Run Organize Import」をチェック．
「Select a code formatting action」で「Run Format」を選択．してください．

↑

FAQ†

↑

mvn javadoc:javadocしたときにJavaDocは生成されるが以下のように「BUILD ERROR」と表示される†

[INFO] snapshot org.seasar.container:s2-framework:2.4.0-beta-4-SNAPSHOT: checkin
g for updates from maven.seasar.org
Downloading: http://maven.seasar.org/maven2/org/seasar/container/s2-framework/2.
4.0-beta-4-SNAPSHOT/s2-framework-2.4.0-beta-4-SNAPSHOT.jar
[WARNING] Unable to get resource from repository maven.seasar.org  http://maven.
seasar.org/maven2)
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Failed to resolve artifact.

Missing:
----------
1) org.seasar.container:s2-framework:jar:2.4.0-beta-4-SNAPSHOT

  Try downloading the file manually from the project website.

  Then, install it using the command:
      mvn install:install-file -DgroupId=org.seasar.container -DartifactId=s2-fr
amework \
          -Dversion=2.4.0-beta-4-SNAPSHOT -Dpackaging=jar -Dfile=/path/to/file

  Path to dependency:
        1) org.seasar.container:s2-extension:jar:2.4.0-beta-4-SNAPSHOT
        2) org.seasar.container:s2-framework:jar:2.4.0-beta-4-SNAPSHOT

----------
1 required artifact is missing.

for artifact:
  org.seasar.container:s2-extension:jar:2.4.0-beta-4-SNAPSHOT

from the specified remote repositories:
  central (http://repo1.maven.org/maven2),
  maven.seasar.org (http://maven.seasar.org/maven2)


[INFO] ------------------------------------------------------------------------
[INFO] For more information, run Maven with the -e switch
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 minute 55 seconds
[INFO] Finished at: Wed Jul 26 21:02:08 JST 2006
[INFO] Final Memory: 7M/13M
[INFO] ------------------------------------------------------------------------

JavaDocは生成されているので実害はないですが気になる場合は「mvn clean install」した後再度生成してください。

↑

SeasarJavadocProject の履歴(No.56)

Seasar Java プロダクトの Javadoc を書こう†

参加手順†

Javadoc の生成手順†

Maven2 のインストール†

Seasar2 のチェックアウト†

Javadoc の生成†

作業手順†

サインアップ†

方針†

表記†

表記がブレそうな言葉を統一†

HTMLタグの使い方を統一†

その他†

レイアウトに関する工夫†

Javadoc よりも他のドキュメントが良い場所†

Eclipse Tips†

Javadoc の生成†

インタフェースを実装したクラスを開く†

Eclipse で Javadoc を扱う便利な方法†

ファイルを保存と同時にフォーマットしてくれるプラグイン†

FAQ†

mvn javadoc:javadocしたときにJavaDocは生成されるが以下のように「BUILD ERROR」と表示される†

ふりかえり†

Containerパッケージ振り返り†

参考資料†

Javadoc タグ†

日本語の書き方†

用語集†