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

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

参加手順

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 が生成されます.

作業手順

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

サインアップ

クラス担当開始日終了日レビュー
AbstractAnnotationHandler.java
AbstractS2ContainerBuilder.javabelltree2006/11/28
AbstractTagHandler.javayatsu2007/01/182007/02/04koichik
AnnotationHandler.javavestige2007/01/24
AnnotationHandlerFactory.javajundu2007/02/20
ArgTagHandler.java
AspectDefFactory.javajundu2007/01/092007/01/17koichik
AspectTagHandler.java
CircularIncludeRuntimeException.javajundu2006/12/262007/01/10koichik
ClassPathResourceResolver.javanomadmonad2007/02/19
ComponentsTagHandler.java
ComponentTagHandler.java
ConstantAnnotationHandler.java
DestroyMethodTagHandler.java
DICapableClassLoader.javajundu2007/01/17廃止予定
IncludeTagHandler.java
InitMethodTagHandler.java
InterTypeTagHandler.java
MetaTagHandler.java
MethodTagHandler.java
PathResolver.javajundu2007/01/202007/02/03koichik
PropertyTagHandler.java
ResourceResolver.javaMaeno2006/12/19
S2ContainerBuilder.javaazusa2006/12/12
S2ContainerFactory.javajundu2006/11/212007/01/10koichik
S2ContainerTagHandlerRule.javayatsu2006/02/042006/02/08koichik
SimplePathResolver.javajundu2007/02/032007/02/20koichik
SingletonS2ContainerFactory.javagoto2006/12/02
TagAttributeNotDefinedRuntimeException.javayatsu2007/03/03
WebResourceResolver.java
XmlS2ContainerBuilder.javayatsu2007/02/082007/02/28koichik
package.html

方針

表記

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

HTMLタグの使い方を統一

その他

レイアウトに関する工夫

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

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」を選んで

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パッケージ振り返り

参考資料

Javadoc タグ

日本語の書き方

用語集


トップ   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS