SeasarJavadocProject の編集

#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]] のレビュー欄にコミッタの名前を入力します．

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

**サインアップ [#a241e451]
|~クラス|~担当|~開始日|~終了日|~レビュー|
|AbstractAnnotationHandler.java|vestige|2006/12/13|2007/6/12||
|AbstractS2ContainerBuilder.java|||||
|AbstractTagHandler.java|yatsu|2007/01/18|2007/02/04|koichik|
|AnnotationHandler.java|vestige|2007/01/24|2007/03/25|koichik|
|AnnotationHandlerFactory.java|jundu|2007/02/20|2007/03/19|koichik|
|ArgTagHandler.java|−|−|−|−|
|AspectDefFactory.java|jundu|2007/01/09|2007/01/17|koichik|
|AspectTagHandler.java|−|−|−|−|
|CircularIncludeRuntimeException.java|jundu|2006/12/26|2007/01/10|koichik|
|ClassPathResourceResolver.java|azusa|2007/06/12|2007/6/22|koichik|
|ComponentsTagHandler.java|−|−|−|−|
|ComponentTagHandler.java|−|−|−|−|
|ConstantAnnotationHandler.java|Maeno|2007/03/08|2007/05/11|koichik|
|DestroyMethodTagHandler.java|−|−|−|−|
|DICapableClassLoader.java|jundu|2007/01/17|廃止|−|
|IncludeTagHandler.java|−|−|−|−|
|InitMethodTagHandler.java|−|−|−|−|
|InterTypeTagHandler.java|−|−|−|−|
|MetaTagHandler.java|−|−|−|−|
|MethodTagHandler.java|−|−|−|−|
|PathResolver.java|jundu|2007/01/20|2007/02/03|koichik|
|PropertyTagHandler.java|−|−|−|−|
|ResourceResolver.java|Maeno|2006/12/19|2007/03/08|koichik|
|S2ContainerBuilder.java|azusa|2006/12/12|2007/03/08|koichik|
|S2ContainerFactory.java|jundu|2006/11/21|2007/01/10|koichik|
|S2ContainerTagHandlerRule.java|yatsu|2006/02/04|2006/02/08|koichik|
|SimplePathResolver.java|jundu|2007/02/03|2007/02/20|koichik|
|SingletonS2ContainerFactory.java|goto|2006/12/02|2007/03/20|koichik|
|TagAttributeNotDefinedRuntimeException.java|yatsu|2007/03/03|2007/03/06|koichik|
|WebResourceResolver.java|yatsu|2007/03/05|2007/05/09|koichik|
|XmlS2ContainerBuilder.java|yatsu|2007/02/08|2007/02/28|koichik|
|package.html|jundu|2007/03/29|2007/05/21|koichik|
***org.seasar.framework.container.creator [#p8752c27]
|~クラス|~担当1|~担当2|~開始日|~終了日|~レビュー|
|ActionCreator.java|vestige||2007/07/27|2007/10/02||
|ComponentCreatorImpl.java|jundu||2007/07/13|2007/09/06|koichik|
|ConverterCreator.java||||||
|DaoCreator.java|yatsu||2007/08/06|2007/11/12|koichik|
|DtoCreator.java|yatsu||2007/11/13|2007/11/15|koichik|
|DxoCreator.java|yatsu||2007/11/13|2007/11/20|koichik|
|HelperCreator.java|yatsu||2007/11/19|2007/12/26|koichik|
|InterceptorCreator.java|yatsu||2007/11/19|||
|LogicCreator.java||||||
|PageCreator.java|vestige||2007/12/16|||
|ServiceCreator.java|vestige||2007/10/03|2007/12/16||
|ValidatorCreator.java||||||
***org.seasar.framework.container.customizer [#e3831119]
|~クラス|~担当1|~担当2|~開始日|~終了日|~レビュー|
|AbstractCustomizer.java|jundu||2007/10/14|2007/12/16|koichik|
|AspectCustomizer.java|jundu||2007/12/03|2007/12/16|koichik|
|CustomizerChain.java|Maeno|2008/2/9||||
|InterTypeCustomizer.java||||||
|MetaCustomizer.java|jundu||2007/12/16|||
***org.seasar.framework.unit [#f411472d]
|~クラス|~担当1|~担当2|~開始日|~終了日|~レビュー|
|S2FrameworkTestCase.java|belltree||2007/09/10|(目標:10/16)||
|UnitClassLoader.java|belltree|goto|2007/07/06|2007/09/30|koichik|
***org.seasar.extension.unit [#yddd1111]
|~クラス|~担当1|~担当2|~開始日|~終了日|~レビュー|
|BeanListReader.java||||||
|BeanReader.java|yatsu||2007/12/17|||
|MapListReader.java||||||
|MapReader.java||||||
|S2TestCase.java||||||
**方針 [#c42c67d2]
-private には書かない
-S2 の利用者が直接使いそうなものから書いていく
-@see の先が出来る前でも @see をとりあえず書いておく
-Javadoc は仕様を書くもの
-実装者の視点ではなく，利用者の視点で読めるように書く
-HTML (HTML 4.01 Transitional を想定) で書く

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

***表記がブレそうな言葉を統一 [#x8712e08]
-日本語と横文字
|~○|~×|
|パフォーマンス|性能|
|レコード|行|
|カラム|列|
|テーブル|表|
|インデックス|索引|
|主キー|プライマリキー|

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

-漢字と数字
|~○|~×|
|1つ|一つ|

-英語
|~○|~×|
|Web|WEB、ウェブ|

-クラス(or Bean)構成要素
|~-|~○|~×|
|~constructor|{@link ClassName}のインスタンスを構築します|〜を作成します|
|~getter|〜を返します|〜を取得します|
|~setter|〜を設定します|〜をセットします|

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

-文中で使用するクラスやインターフェースの日本語名
--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} (初回) または <code>InterfaceName</code> (２回目以降)|
|クラス名|{@link ClassName} (初回) または <code>ClassName</code> (２回目以降)|
|メソッド名|{@link #methodName} または {@link #methodName(String)}|
|フィールド名|{@link #instanceField}, {@link #classField}|
|変数名|<code>localVariable</code>, <code>parameter</code>|

--逆引き

--良くない例

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

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

**ふりかえり [#l7902e02]
***Containerパッケージ振り返り [#t26565c7]
-[[SeasarJavadocProject/org.seasar.framework.container/KPT]]

**参考資料 [#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]]

タイムスタンプを変更しない