[seasar-javadoc:509] Re: S2Container

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Wed, 9 Aug 2006 01:38:34 +0900
From:    "Makoto Yonezawa" <stratosphire ＠ gmail.com>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:506] Re: S2Container

> すこし息を吹き返しそうです・・・

頑張れぇ〜．

> * 指定されたキーに対応する複数のコンポーネントを検索して返します。

ここはいいと思います．

> * <P>
> * 検索されるコンポーネントについて

些細なことですが，これだけだと Javadoc (HTML) では見出しにならなくて，
空白一つ挟んで次の行が続いてしまいます．
クラスコメントだったら <h4>〜</h4> とか使うところですが，
メソッドコメントで見出しというのもやりすぎ感があるので，
ここは段落を分けるだけで見出しは無しにしましょう．

> * 現在のS2コンテナおよび、インクルードされているS2コンテナの階層から、
> * キーに対応するコンポーネントが最初に見つかったS2コンテナに登録されている
> * 全てのコンポーネントを検索します。
> * </P>

最後のところがちょっと気になるかなぁ．
「全てのコンポーネントを検索します」が，キーに対応する複数の
コンポーネントだということが分かりにくいかな，と．
でもでも，

 * 現在のS2コンテナおよび、インクルードされているS2コンテナの階層から、
 * キーに対応するコンポーネントが最初に見つかったS2コンテナに登録されている、
 * キーに対応する全てのコンポーネントを検索します。

だと明らかにくどい．
難しいですね．うーん．．．
箇条書きっぽくしてみる？

 * 検索の対象は現在のS2コンテナおよび、インクルードしているS2コンテナの階層全体です。
 * S2コンテナ階層から、キーに対応するコンポーネントが最初に見つかったコンテナを選択します。
 * 選択したコンテナから，キーに対応する全てのコンポーネントを配列で返します。

みたいな．

> * <P>
> * コンポーネントの検索順について
> * 最初にメソッドが呼びだされたS2コンテナ、
> * 次に、インクルードされているS2コンテナの順番にしたがって検索をします。
> * </P>

ここも見出しっぽいのは無しで，「コンポーネントの検索順は、〜」って
感じで．

> * <P>
> * 返される配列に含まれるコンポーネントは全て同一のS2コンテナに登録されたものです。
> * </P>

これは上に移動したいかなぁ．
箇条書きの最後に追加するとか．

> * <P>
> * インクルードされているS2コンテナの階層全体に対して、
> * キーに対応した全てのコンポーネントを検索する場合には{@link #findAllComponents}を使用してください。
> * メソッドが呼び出されるS2コンテナに対してのみ、
> * 登録されているコンポーネントだけを検索する場合には{@link #findLocalComponents}を使用してください
> * </P>

これは @see で十分かも．
それぞれのメソッドで説明があるわけなので．

> * <P>
> * キーが文字列の場合、名前が一致するコンポーネントを返します。
> * キーがクラスまたはインターフェースの場合、キーの型に代入可能なコンポーネントを返します。
> * キーに対応するコンポーネントが存在しない場合は空の配列を返します。
> * </P>

これは @return に書いてもいいかも．

> *
> * @param componentKey
> *            コンポーネントを取得するためのキー
> * @return コンポーネントの配列
> * @throws CyclicReferenceRuntimeException
> *             コンストラクター・インジェクションでコンポーネントの参照が循環している場合
> */
> 

@return は上の段落を持ってくるということで．

> これからすると、
> findAllComponents、findLocalComponentsも一文ではなく、もう少し説明が要りますよね？

そうですね．基本的に同じ形にしましょう．

> それと、@linkも必要でしょうか？

@link というか @see を相互に書きましょう．

> また、find〜Defsも〜定義が変わるだけですが、同様な説明が必要ですよね？

ですね．


> 最後に、クラスメソッドの件です。
>     概要
>         S2コンテナはSeasarの基本的な部分
>         diconファイルの設定で動作する
>     仕組み
>         コンテナ生成
>         初期化
>         コンポーネント取得
>         メソッド実行
>     インジェクション
>         ３つの種類
> 
> こんな感じのアジェンダを考えたのですが・・・ここまではいらない？
> ですか？

そうですねぇ．
「概要」の「diconファイルの設定で動作する」は少し微妙．
S2Container は dicon ファイル無しでも使えますからね．

「仕組み」は「ライフサイクル」とした方がいいですね．
その前に「構造」みたいなのが欲しいかなぁ．
構造というのは，S2コンテナはインクルードされたコンテナと
コンポーネント定義を持ち，階層を成しているということ．
一つのコンテナは複数のコンテナをインクルードすることができて，
一つのコンテナは複数のコンテナからインクルードされることが
できるということ．
一つのコンポーネント定義は一つのコンテナにしか
所有されないということ．
などなど．


-- 
<component name="koichik">
    <property name="fullName">"Koichi Kobayashi"</property>
    <property name="email">"koichik ＠ improvement.jp"</property>
    <property name="blog">"http://d.hatena.ne.jp/koichik"</property>
</component>