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を生成して「リンク切れ」や「レイアウトの崩れ」がないかブラウザで確認してください.
  • ML でレビュー
    Javadoc を記述したソースを添付して seasar-javadoc ML へ投稿してください. 他のメンバーから指摘された点について議論・修正を行って再度投稿をしてください.
  • コミット
    1 名以上の開発担当コミッタから承認があり,他のメンバーから指摘がなければ SVN にコミットします. その際のコミットログは
    added Javadoc comment.
    としてください. 一度コミットした後,Javadoc コメントを修正した場合のコミットログは
    modified Javadoc comment.
    としてください.
  • 終了日の入力
    Javadoc コメントのコミットが完了したクラスについて,サインアップ の終了日にその日付,レビュー欄に承認した開発担当コミッタのアカウント名を入力してください.

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

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

サインアップ

クラス担当開始日終了日レビュー
AbstractAnnotationHandler.javavestige2006/12/132007/6/12
AbstractS2ContainerBuilder.java
AbstractTagHandler.javayatsu2007/01/182007/02/04koichik
AnnotationHandler.javavestige2007/01/242007/03/25koichik
AnnotationHandlerFactory.javajundu2007/02/202007/03/19koichik
ArgTagHandler.java
AspectDefFactory.javajundu2007/01/092007/01/17koichik
AspectTagHandler.java
CircularIncludeRuntimeException.javajundu2006/12/262007/01/10koichik
ClassPathResourceResolver.javaazusa2007/06/122007/6/22koichik
ComponentsTagHandler.java
ComponentTagHandler.java
ConstantAnnotationHandler.javaMaeno2007/03/082007/05/11koichik
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/192007/03/08koichik
S2ContainerBuilder.javaazusa2006/12/122007/03/08koichik
S2ContainerFactory.javajundu2006/11/212007/01/10koichik
S2ContainerTagHandlerRule.javayatsu2006/02/042006/02/08koichik
SimplePathResolver.javajundu2007/02/032007/02/20koichik
SingletonS2ContainerFactory.javagoto2006/12/022007/03/20koichik
TagAttributeNotDefinedRuntimeException.javayatsu2007/03/032007/03/06koichik
WebResourceResolver.javayatsu2007/03/052007/05/09koichik
XmlS2ContainerBuilder.javayatsu2007/02/082007/02/28koichik
package.htmljundu2007/03/292007/05/21koichik

org.seasar.framework.container.creator

クラス担当1担当2開始日終了日レビュー
ActionCreator.javavestige2007/07/272007/10/02
ComponentCreatorImpl.javajundu2007/07/132007/09/06koichik
ConverterCreator.java
DaoCreator.javayatsu2007/08/062007/11/12koichik
DtoCreator.javayatsu2007/11/132007/11/15koichik
DxoCreator.javayatsu2007/11/132007/11/20koichik
HelperCreator.javayatsu2007/11/192007/12/26koichik
InterceptorCreator.javayatsu2007/11/19
LogicCreator.java
PageCreator.javavestige2007/12/16
ServiceCreator.javavestige2007/10/032007/12/16
ValidatorCreator.java

org.seasar.framework.container.customizer

クラス担当1担当2開始日終了日レビュー
AbstractCustomizer.javajundu2007/10/142007/12/16koichik
AspectCustomizer.javajundu2007/12/032007/12/16koichik
CustomizerChain.javaMaeno2008/2/9
InterTypeCustomizer.java
MetaCustomizer.javajundu2007/12/16

org.seasar.framework.unit

クラス担当1担当2開始日終了日レビュー
S2FrameworkTestCase.javabelltree2007/09/10(目標:10/16)
UnitClassLoader.javabelltreegoto2007/07/062007/09/30koichik

org.seasar.extension.unit

クラス担当1担当2開始日終了日レビュー
BeanListReader.java
BeanReader.javayatsu2007/12/17
MapListReader.java
MapReader.java
S2TestCase.java

方針

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

表記

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

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

  • 日本語と横文字
    ×
    パフォーマンス性能
    レコード
    カラム
    テーブル
    インデックス索引
    主キープライマリキー
  • 横文字
    ×
    ユーザユーザー
    インターフェースインタフェース
    クラスローダクラスローダー
    ファクトリファクトリー
    インターセプタインターセプター
    コンフィギュレーション?コンフィグレーション?
    ビルダ? ビルダー??
  • ひらがなと漢字
    ×
    ください下さい
    ..の方..のほう
    既にすでに
    主な(に)おもな(に)
    出来ますできます
    良いよい
    など
    例えばたとえば
    そのとおりその通り
    行なう行う
  • 漢字と数字
    ×
    1つ一つ
  • 英語
    ×
    WebWEB、ウェブ
  • クラス(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プロパティ定義
      S2ContainerS2コンテナ

HTMLタグの使い方を統一

  • 順引き
    • <code>〜</code> (一部 {@link 〜} を含む)
      • キーワード(予約語)
        Aabstractassert
        Bbooleanbreakbyte
        Ccasecatchcharclassconstcontinue
        Ddefaultdodouble
        Eelseenum*extends
        Ffinalfinallyfloatfor
        Ggoto
        Iifimplementsimportinstanceofintinterface
        Llong
        Nnativenew
        Ppackageprivateprotectedpublic
        Rreturn
        Sshortstaticstrictfpsuperswitchsynchronized
        Tthisthrowthrowstransienttry
        Vvoidvolatile
        Wwhile
  • 識別子
    識別子
    インターフェース名{@link InterfaceName} (初回) または <code>InterfaceName</code> (2回目以降)
    クラス名{@link ClassName} (初回) または <code>ClassName</code> (2回目以降)
    メソッド名{@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での「"」「&」「<」「>」
      @&#064;
      "&quot;
      &&amp;
      <&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パッケージ振り返り

参考資料

Javadoc タグ

日本語の書き方

用語集


トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2008-02-09 (土) 00:43:58 (3514d)