[seasar-javadoc:948] Re: AbstractS2ContainerBuilder

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Sun, 1 Jul 2007 23:31:01 +0900
From:    "Naoki Sega" <[E-MAIL ADDRESS DELETED]>
To:      [E-MAIL ADDRESS DELETED]
Subject: [seasar-javadoc:946]  AbstractS2ContainerBuilder

> AbstractS2ContainerBuilderのJavaDocを
> 書きましたので、レビューをよろしくお願いいたします。

お疲れ様でした！！

> なんとか書き上げてみましたが、
> ７月に入ってしまいました。すいません。

いえいえ，全然問題ありません．
マイペースでやっていただいて構わないですよ．

以下，コメントです．

■クラスコメント

>  * S2ContainerBuilderrの抽象クラスです。
>  * 
>  * <p>
>  * 特定の形式の定義情報から{@link org.seasar.framework.container.S2Container S2コンテナ}
>  * を組み立てるビルダです。
>  * </p>

<p>〜</p> の中はインタフェースから持ってきてますよね．
その場合はいっそ，

 * 特定の形式の定義情報から{@link org.seasar.framework.container.S2Container S2コンテナ}を組み立てるビルダの抽象クラスです。

で十分な気のせいが．

■resourceResolver

>      * クラスパス経由でのリソースの取得方法{@link ResourceResolver ResourceResolver}を構築します。

ここは初期化子の説明ではなく，フィールドの説明を
お願いします．
「クラスパス経由で〜」はデフォルトで使用する
ClassPathResourceResolver がたまたまそうだということで，
このフィールド自体にはその意味はないのでこれはなくすか，
書くとしても，「デフォルトでは〜」みたいな感じで．

それから，これだと Java Doc で見たときに

クラスパス経由でのリソースの取得方法ResourceResolverを構築します。

となってしまい，ちょっと変な感じです．
もし {@link 〜} を使うなら

{@link ResourceResolver リソースの取得方法}

みたいにするとか．
また，

{@link ResourceResolver ResourceResolver}

のようにリンクの文字列とリンク先が同じ場合は

{@link ResourceResolver}

と省略しませう．

これは getter/setter も同様．

■getResourceResolver()

get〜() は「〜を返します」で揃えている (たぶん) ので
ここもそれでお願いします．

■build(final String path, final ClassLoader classLoader)

インタフェースで定義されているメソッドの場合は
Javadoc を書く必要がありません．
実装上の説明を加えるのなら書いてもいいのですが，
この場合のようにインタフェースの記述そのままの場合は
省略しませう．
生成される Javadoc にはちゃんとインタフェースに
書かれているコメントが出力されます．

■getInputStream(final String path)

     * 読み込み対象となるリソースから入力ストリームを返します。
                                 ^^^^
細かくてスミマセンが，ここは「リソースの」の方が
いいかなぁ．


口うるさい印象のコメントになってしまった．心より恥じる．



-- 
<component name="koichik">
    <property name="fullName">"Koichi Kobayashi"</property>
    <property name="email">"[E-MAIL ADDRESS DELETED]"</property>
    <property name="blog">"http://d.hatena.ne.jp/koichik"</property>
</component>