[seasar-javadoc:87] Re: ツッコミ大歓迎! 叩き台サンプル

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Mon, 29 May 2006 08:36:05 +0900
From:    Hideaki Suzuki <suzuki ＠ uinet.or.jp>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:73] ツッコミ大歓迎! 叩き台サンプル

> 【恥を】
> 課題の洗い出しと、Javadoc Wiki に規約として載せるネタ出しのために、
> 自分が追加したJavadocコメント（付きソース）を添付しました。
> 【忍んで】
> 
> 遠慮なく突っ込んでやって下さい。宜しくお願いします。

ということで少々．
まずはクラスへのコメントから．

>  * アクセスタイプの定義です。

「フィールドまたはプロパティへのアクセス方法の定義です。」
のように最初から説明的にした方がいいかなぁ，とか．

> アクセスタイプ には、 <code>property</code>タイプ
> <code>field</code>タイプ の2種類があります。

ここで <code>〜</code> を使うのはおかしな気が．

アクセスタイプには「フィールド」アクセスタイプと
「プロパティ」アクセスタイプの2種類があります。

って感じでいいような．
あと，記述順を フィールド -> プロパティかその逆かで
統一した方がいいかなとか．

>  * <code>AccessTypeDef</code>は、<code>{@link PropertyDef}</code>の属性です。

これがあるのなら，

>  * @see PropertyDef

こっちはなくてもいいような．
合っても悪くはないですが，きりがないので．
関連の強いものはできるだけ本文中で {@link 〜} を
使ってその関係を示して，その場合は @see なしでも
いいんじゃないかと思います．


次は定数へのコメント

>      * <code>property</code>タイプを表すリテラルです。

ここは「定数です」にしましょう．
リテラルというと "field" のことで，ココで説明しているのは
そのリテラルで値を設定された PROPERTY_NAME であり，それは
リテラルそのものではなくて定数です．


次は getName() メソッド．

>      * アクセスタイプ名を取得できます。

getter メソッドは「〜を返します」という表現にしましょう．
# JDK の Javadoc の多くがそのパターン．
setter メソッドは「〜を設定します」で．


最後に bind() メソッド．

>      * コンポーネント定義、プロパティ定義、及び自身のアクセスタイプ定義に基づいて、 DIコンテナ上のオブジェクトグラフに、
>      * コンポーネントをバインドします。

冒頭の「コンポーネント定義、プロパティ定義、及び自身の」は
なくてもいいかな，と．

その後の文章は説明が逆っぽい．
これだと引数のコンポーネント「を」コンテナ上のオブジェクト「に」バインド
するみたいですが，実際は引数のコンポーネント「に」コンテナ上の
オブジェクト「を」バインドします．

<component class="Foo">
  <property name="bar">hoge</property>
</component>

とあった場合，コンポーネント定義は <component> の
情報を持ち，プロパティ定義は <property> の情報を持ちます．
そして Foo のインスタンスがコンポーネントです．
この Foo のインスタンスすなわちコンポーネントのプロパティ
bar (これを表すのが PropertyDesc) に対して，コンテナ上の
オブジェクト (これもコンポーネントだけど) hoge を DI するのが
このメソッドの責務です．
なので，

アクセスタイプに基づいて、コンポーネントのプロパティまたはフィールドに
コンテナ上のオブジェクトを割り当てます．

とかでどうでしょう？


-- 
<signature>
    <name>Koichi Kobayashi</name>
    <e-mail>koichik ＠ improvement.jp</e-mail>
</signature>