SeasarJavadocProject

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

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

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

サインアップ †

org.seasar.framework.container.creator †

org.seasar.framework.container.customizer †

org.seasar.framework.unit †

org.seasar.extension.unit †

方針 †

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

表記 †

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

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

• 日本語と横文字

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

• 横文字

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

• ひらがなと漢字

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

• 漢字と数字

  ○	×
  1つ	一つ

• 英語

  ○	×
  Web	WEB、ウェブ

• クラス(or Bean)構成要素

  -	○	×
  constructor	{@link ClassName}のインスタンスを構築します	〜を作成します
  getter	〜を返します	〜を取得します
  setter	〜を設定します	〜をセットします

• JavaEE用語

  ○	×	意味
  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} (初回) または <code>InterfaceName</code> (２回目以降)
  クラス名	{@link ClassName} (初回) または <code>ClassName</code> (２回目以降)
  メソッド名	{@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>

• Seasar関係

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

• 逆引き

• 良くない例

その他 †

• 説明文の記述パターン

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

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

    @	@
    "	"
    &	&
    <	&lt;
    >	&gt;

• @authorに自分の名前を追記するとき
  • Javadocに自分の名前を追記するときは、名前の後に(Javadoc)を追記します。 (JavaDoc)の追加はしないことになりました。
• @throwsの記述方針
  • インターフェースで例外を記述するときは、実装クラス側でスローする可能性のある例外をすべて記述します。
• @linkと<code>の使い分け(クラス名の記述)
  • コメントブロックの中で、1つのクラス名を複数記述する場合、初回の記述は @link を使用し、2回目以降は <code> を使用します。
• 修飾名と非修飾名
  • 同じパッケージに属するクラスを記述する場合、修飾名で書かなくても良いです。クラス名だけで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」した後再度生成してください。

ふりかえり †

Containerパッケージ振り返り †

• SeasarJavadocProject/org.seasar.framework.container/KPT

参考資料 †

Javadoc タグ †

• javadoc - Java API ドキュメントジェネレータ / Javadoc タグ

日本語の書き方 †

• プロジェクト jdk-api-ja / 日本スタイルガイド(PDF)

用語集 †

• プロジェクト jdk-api-ja / Sun Gloss (用語集の利用には登録が必要)