- 追加された行はこの色です。
- 削除された行はこの色です。
#contents
*Seasar Java プロダクトの Javadoc を書こう [#nd917e51]
Seasar Javadoc Project は，Seasar2 を始めとする Java プロダクトに Javadoc コメントを記述していくプロジェクトです．~
Seasar Javadoc Project にはどなたでも参加できます．~
協力して頂ける方を募集しています．
実行力のある方大歓迎！！
**参加手順 [#x0883e25]
-[[seasar-javadoc ML:https://www.seasar.org/mailman/listinfo/seasar-javadoc]] にて参加表明してください．
-seasar.org のアカウントを持っていない人は参加表明に以下のフォームでアカウントの申請を記述してください．
氏名・ハンドルネーム:
連絡先メールアドレス: (スパムロボットに収集されないように改変可能)
ブログ／ホームページのURL： (もしあれば)
希望アカウント名
第一希望: ( svnでSeasar.orgにcommit
第二希望: する時のアカウント )
**Javadoc の生成手順 [#w3d1a5ca]
***Maven2 のインストール [#med15997]
Javadoc の生成は Maven2 で行います．
Maven2 は以下からダウンロードすることができます (インストール手順というか設定もあります)．
http://maven.apache.org/download.html#installation
***Seasar2 のチェックアウト [#yfce6013]
Eclipse で SVN からチェックアウトします．
Seasar2 のリポジトリの URL は以下です．
https://www.seasar.org/svn/s2container/
Javadoc の記述は trunk で行います．
trunk/seasar2 をチェックアウトしてください．
***Javadoc の生成 [#zdb9fc55]
コマンドプロンプトを開いて seasar2 ディレクトリへ
移動します．~
次のコマンドを実行します．
mvn javadoc:javadoc
seasar2/s2-framework/target/site/apidocs ディレクトリに Javadoc が生成されます．
**作業手順 [#ybb7efe6]
-対象となるパッケージの決定~
Javadoc コメントは参加者全員が1つのパッケージに集中して作業していきます．
対象となるパッケージは seasar-javadoc ML にて決定します．
-サインアップ~
参加者は担当するクラスを決定し，[[サインアップ>#g3bafca0]] 一覧の担当者名にアカウント名，開始日欄にサインアップした日付を記入します．~
担当するクラスは一度に多く取りすぎないようにしてください (未完了のクラス == 在庫を増やさないようにするため)．~
担当する未完了のクラス数は原則として上限を 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を生成>#zdb9fc55]]して「リンク切れ」や「レイアウトの崩れ」がないかブラウザで確認してください．
-ML でレビュー~
Javadoc を記述したソースを添付して seasar-javadoc ML へ投稿してください．
他のメンバーから指摘された点について議論・修正を行って再度投稿をしてください．
-コミット~
1 名以上の開発担当コミッタから承認があり，他のメンバーから指摘がなければ SVN にコミットします．
その際のコミットログは
added Javadoc comment.
としてください．
一度コミットした後，Javadoc コメントを修正した場合のコミットログは
modified Javadoc comment.
としてください．
-終了日の入力~
Javadoc コメントのコミットが完了したクラスについて，[[サインアップ>#g3bafca0]] の終了日にその日付，レビュー欄に承認した開発担当コミッタのアカウント名を入力してください．
問題がなければ [[サインアップ>#g3bafca0]] のレビュー欄にコミッタの名前を入力します．
-完了~
パッケージ内の全てのクラスのレビューが終了したら完了となり，次のパッケージの作業を開始します．
**方針 [#c42c67d2]
-private には書かない
-S2 の利用者が直接使いそうなものから書いていく
-@see の先が出来る前でも @see をとりあえず書いておく
-Javadoc は仕様を書くもの
-実装者の視点ではなく，利用者の視点で読めるように書く
-HTML (HTML 4.01 Transitional を想定) で書く
**サインアップ [#g3bafca0]
-org.seasar.framework.container パッケージ
|~クラス|~担当|~開始日|~終了日|~レビュー|
|package.html|belltree|2006/08/02|||
|AccessTypeDef|belltree|2006/05/28|2006/06/07|koichik|
|ArgDef|vestige|2006/05/28|2006/06/07|koichik|
|ArgDefAware|jundu|2006/08/09|2006/08/15|koichik|
|AspectDef|belltree|2006/06/26|2006/06/29|koichik|
|AspectDefAware|belltree|2006/07/11|2006/07/13|koichik|
|AutoBindingDef|jundu|2006/05/28|2006/06/12|koichik|
|BindingTypeDef|jundu|2006/05/28|2006/06/01|koichik|
|ClassUnmatchRuntimeException|belltree|2006/07/03|2006/07/09|koichik|
|ComponentCreator|||||
|ComponentCreator|jundu|2006/08/29|||
|ComponentCustomizer|||||
|ComponentDef|belltree|2006/06/02|2006/07/09|koichik|
|ComponentDeployer|belltree|2006/07/03|2006/07/15|koichik|
|ComponentNotFoundRuntimeException|belltree|2006/07/12|2006/07/13|koichik|
|ConstructorAssembler|jundu|2006/06/06|2006/06/26|koichik|
|ContainerConstants|belltree|2006/07/13|2006/07/16|koichik|
|ContainerNotRegisteredRuntimeException|belltree|2006/07/15|2006/07/16|koichik|
|CyclicReferenceRuntimeException|belltree|2006/07/15|2006/07/16|koichik|
|DestroyMethodDef|belltree|2006/07/16|2006/07/23|koichik|
|DestroyMethodDefAware|belltree|2006/07/16|2006/07/20|koichik|
|Expression|goto|2006/06/11|2006/06/18|koichik|
|ExtensionNotFoundRuntimeException|belltree|2006/07/19|2006/07/23|koichik|
|ExternalContext|goto|2006/06/11|2006/06/18|koichik|
|ExternalContextComponentDefRegister|belltree|2006/07/20|2006/07/30|koichik|
|IllegalAccessTypeDefRuntimeException|belltree|2006/07/22|2006/07/23|koichik|
|IllegalAutoBindingDefRuntimeException|jundu|2006/07/05|2006/07/11|koichik|
|IllegalAutoBindingPropertyRuntimeException|jundu|2006/07/11|2006/07/24|koichik|
|IllegalBindingTypeDefRuntimeException|jundu|2006/06/01|2006/06/12|koichik|
|IllegalConstructorRuntimeException|jundu|2006/07/20|2006/07/24|koichik|
|IllegalDestroyMethodAnnotationRuntimeException|jundu|2006/07/22|2006/07/26|koichik|
|IllegalInitMethodAnnotationRuntimeException|belltree|2006/07/24|2006/07/26|koichik|
|IllegalInstanceDefRuntimeException|jundu|2006/07/26|2006/08/02|koichik|
|IllegalMethodRuntimeException|belltree|2006/07/27|2006/07/29|koichik|
|InitMethodDef|matsunobu|2006/06/05|2006/07/09|koichik|
|InitMethodDefAware|belltree|2006/07/26|2006/07/29|koichik|
|InstanceDef|goto|2006/05/30|2006/06/06|koichik|
|InterTypeDef|Maeno(xenon)|2006/07/19|||
|InterTypeDefAware|Maeno(xenon)|2006/07/19|||
|MetaDef|nomadmonad|2006/06/12|2006/08/02|koichik|
|MetaDefAware|nomadmonad|2006/07/04|2006/08/17|koichik|
|MethodAssembler|azusa|2006/06/27|2006/07/15|koichik|
|MethodDef|azusa|2006/06/01|2006/06/25|koichik|
|PropertyAssembler|jundu|2006/06/19|2006/07/11|koichik|
|PropertyDef|xenon|2006/5/31|2006/7/16|koichik|
|PropertyDefAware|Maeno(Xenon)|2006/7/15|2006/7/16|koichik|
|S2Container|vestige|2006/05/28|||
|TooManyRegistrationComponentDef|azusa|2006/07/20|2006/08/08|koichik|
|TooManyRegistrationRuntimeException|belltree|2006/07/30|2006/08/02|koichik|
**表記 [#cdda9eec]
-SUN に合わせて「ですます調」で
-句読点は「、。」で
-英数は1byte文字で。2bytes文字との間に空白を入れない。
-数字は(いわゆる)半角に統一
-カタカナは(いわゆる)全角に統一
-機種依存文字は使用禁止
***表記がブレそうな言葉を統一 [#x8712e08]
-日本語と横文字
|~○|~×|
|パフォーマンス|性能|
|レコード|行|
|カラム|列|
|テーブル|表|
|インデックス|索引|
|主キー|プライマリキー|
-横文字
|~○|~×|
|ユーザ|ユーザー|
|インターフェース|インタフェース|
|クラスローダ|クラスローダー|
|ファクトリ|ファクトリー|
|インターセプタ|インターセプター|
|コンフィギュレーション?|コンフィグレーション?|
|ビルダ? ビルダー?|?|
-ひらがなと漢字
|~○|~×|
|ください|下さい|
|..の方|..のほう|
|既に|すでに|
|主な(に)|おもな(に)|
|出来ます|できます|
|良い|よい|
|など|等|
|例えば|たとえば|
|そのとおり|その通り|
|行なう|行う|
-漢字と数字
|~○|~×|
|1つ|一つ|
-英語
|~○|~×|
|Web|WEB、ウェブ|
-getterとsetter
|~-|~○|~×|
|~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タグの使い方を統一 [#ef267f3d]
-順引き
--<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>|
---Seasar関係
|~種類|~例|
|diconファイルのタグ名|<code>component</code>タグの…|
|diconファイルの属性名|<code>instance</code>属性で…|
--逆引き
--良くない例
***その他 [#k3e2730a]
-説明文の記述パターン
|~記述内容|~例|
|デフォルト値の記述|<dt>singleton (default)</dt>？|
|定数値を返すメソッドの記述|コンポーネント定義の文字列表現を返します。|
-文字参照
--「@」はJavadoc上特殊な文字なので、「@」を特別な意味を持たない文字として記述する場合は文字参照を使用します。~
コメントの先頭や中括弧「{}」の先頭に「@」がある場合にのみ「@」は特殊な働きをしますが、このようにしておけば「@」の記述位置を気にする必要がなくなります。~
--HTMLでの「"」「&」「<」「>」
|@|&#064;|
|"|&quot;|
|&|&amp;|
|<|&lt;|
|>|&gt;|
-@authorに自分の名前を追記するとき
--Javadocに自分の名前を追記するときは、名前の後に(Javadoc)を追記します。
-@throwsの記述方針
--インターフェースで例外を記述するときは、実装クラス側でスローする可能性のある例外をすべて記述します。
-@linkと<code>の使い分け
--@linkと<code>は併用しません。@linkだけでOK。
-修飾名と非修飾名
--同じパッケージに属するクラスを記述する場合、修飾名で書かなくても良いです。クラス名だけでOK。
-戻り値がbooleanのメソッドの @return の記述
>>
@return 〜の場合<code>true</code>
<<
***レイアウトに関する工夫 [#ee1c280b]
-フォーマット(Ctrl+Shift+F)時に、なるべく句読点の位置で改行させる工夫
--読点(、) の後ろには (いわゆる) 半角スペースを入れる．
--句点(。) の後ろでは改行する．
**Javadoc よりも他のドキュメントが良い場所 [#x6cd047c]
-interceptors
--これは Javadoc あった方がよいのでは？
-継承して使うことがある場所
--ResultSetHandler
**Eclipse Tips [#gf363f65]
***Javadoc の生成 [#k477d0ba]
クラスまたはメソッドを選んで右クリック「ソース」−「コメントの追加」(ショートカットは Ctrl+Shift+J)．
***インタフェースを実装したクラスを開く [#c9e721b8]
Java エディタでインタフェースを開いている時に Ctrl+T で実装クラスがポップアップ表示されエディタで開くことができます．
***Eclipse で Javadoc を扱う便利な方法 [#u1b986aa]
ソースコードを追う時には Javadoc は邪魔なんじゃい！ヽ(`Д´)ﾉ~
という方。Eclipse をご利用であれば、設定の [Java]-[エディター] のフォールディングタブを開いてください。それから「コメント」をチェック。次から開くソースコードはデフォルトでコメントが折りたたまれています。~
また、Eclipse で Javadoc を参照するのに便利な方法が二つあります。~
一つは Javadoc ビューを開くこと。キャレット (カーソル) がある位置の Javadoc の内容が、HTML レンダリングされて Javadoc ビューに表示されます。~
もう一つは、[Java]-[エディター] の吹き出しタブで「Javadoc」にチェックを入れてください。修飾キーに適当なもの (Alt とか) を設定しましょう。その修飾キーを押しながらメソッド名などをポイントすることで HTML レンダリングされた Javadoc が表示されるようになります。
***ファイルを保存と同時にフォーマットしてくれるプラグイン [#h8b2687f]
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 [#qffb12d6]
***mvn javadoc:javadocしたときにJavaDocは生成されるが以下のように「BUILD ERROR」と表示される [#me28d53b]
[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」した後再度生成してください。
**参考資料 [#fe26449a]
***Javadoc タグ [#y09c62b2]
-[[javadoc - Java API ドキュメントジェネレータ / Javadoc タグ:http://java.sun.com/j2se/1.5.0/ja/docs/ja/tooldocs/windows/javadoc.html#javadoctags]]
***日本語の書き方 [#k5b9c401]
-[[プロジェクト jdk-api-ja / 日本スタイルガイド(PDF):http://developers.sun.com/techtopics/global/technology/translation/style-guides/JA-rule.pdf]]
***用語集 [#n7790f1a]
-[[プロジェクト jdk-api-ja / Sun Gloss (用語集の利用には登録が必要):https://jdk-api-ja.dev.java.net/ja/index.html]]
**ぴあボード(peer board) [#w5fd8c92]
Javadoc-ML上で行われているディスカッションの補助を目的としたメモです。
***Javadocコメントの振り返り 【読む目的 x 記載内容】 [#pd72168a]
-読む目的とあるとうれしい記載内容の関係
|~記載内容＼読む目的|~☆一部の機能を使いたい|~☆機能を拡張したい|~トラブルの原因調査|~理解を深めたい|~使い方を知りたい|
|~コードサンプル||||||
|~拡張ポイント||||||
|~拡張時の注意点||||||
|~実装クラスの解説||||||
|~大まかな構成||||||
|~メソッドの処理概要||||||
|~例外と可能性の高い発生原因||||||
|~クラスの関連図||||||
|~クラスの関連説明||||||
|~Diconファイルとソースの関連||||||
|~S2のドキュメントとソース関連||||||
***Javadocコメントの振り返り 【パターン別統一ポイント】 [#p19fd84d]
-記述内容の検証ポイント
--処理記述について
---「（どうやるかではなく）何をするか」という記述になっているか？(特にインターフェース)
-全般
--統一ポイント
-〜Def系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|AccessTypeDef||
|ArgDef||
|AspectDef||
|AutoBindingDef||
|BindingTypeDef||
|ComponentDef||
|InstanceDef||
|InterTypeDef||
|MetaDef||
|MethodDef||
|PropertyDef||
|InitMethodDef||
|DestroyMethodDef||
|TooManyRegistrationComponentDef||
-〜Aware系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|ArgDefAware||
|AspectDefAware||
|DestroyMethodDefAware||
|InitMethodDefAware||
|InterTypeDefAware||
|MetaDefAware||
|PropertyDefAware||
-コンポーネント組み立て系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|ConstructorAssembler||
|MethodAssembler||
|PropertyAssembler||
-〜DefRuntimeException系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|IllegalAccessTypeDefRuntimeException||
|IllegalAutoBindingDefRuntimeException||
|IllegalBindingTypeDefRuntimeException||
|IllegalInstanceDefRuntimeException||
-指定によるコンポーネント組み立て失敗例外系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|IllegalConstructorRuntimeException||
|IllegalAutoBindingPropertyRuntimeException||
|IllegalMethodRuntimeException||
-アノテーション不正例外系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|IllegalInitMethodAnnotationRuntimeException||
|IllegalDestroyMethodAnnotationRuntimeException||
-その他の例外系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|ClassUnmatchRuntimeException||
|ComponentNotFoundRuntimeException||
|ContainerNotRegisteredRuntimeException||
|CyclicReferenceRuntimeException||
|ExtensionNotFoundRuntimeException||
|TooManyRegistrationRuntimeException||
-定数定義系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|ContainerConstants||
-大物系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|S2Container||
-外部コンテキスト系
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|ExternalContext||
|ExternalContextComponentDefRegister||
-その他(未分類)
--統一ポイント
--修正ポイント
|~クラス/インターフェース_________________|~修正ポイント________________________________________|
|Expression||
|ComponentDeployer||
![[PukiWiki]](image/seasar.png "[PukiWiki]")
