[seasar-javadoc:519] Re: KPT org.seasar.framework.container.*

Jundo Ishikawa jundo.ishikawa @ gmail.com
2006年 8月 22日 (火) 17:22:17 JST


 JUNDUです。Javadocの内容チェック用に想定する読者というかチェックポイントを
少し考えてみました。一般論的になってしまいますが、こんな感じでいかがでしょう
か?

共通して必要なもの
・クラスの責務
 →そのクラスの仕事は何か。何のために存在するのか。
 →そのクラスではやらないことは何か
・事前条件
 →引数とクラスの状態。投げられる例外。
・処理内容
 →どうやるかではなく、何をするか。
・事後条件
 →戻り値とクラスの状態が変わる場合はクラスの状態。

想定する読者と求めるもの
・Seasar2の一部機能を使うためにソースを読もうと思った人。
 →使いたいと思ったクラスの使い方サンプル。
  主にUtilパッケージ配下とS2ContainerやS2SontainerFactoryなど。

・Seasar2の機能を拡張して新しい機能等を作成することを考えている人。
 →拡張可能なポイントと拡張時の注意点。
 →IntercepterやInterTypeなどの骨格実装クラスの説明。

・Seasar2でトラブルがあり、ソースを読むことになった人。
 →必要最小限のところを読むために、大まかな構成。
 →各メソッドの大まかな処理内容。
 →例外の発生原因?

・Seasar2の理解を深めるためにソースを読もうと思った人。
 →クラスの関連図(サンタさんのプレゼント強化版)
 →クラスの関連の説明(パッケージコメント)
 →Diconファイルとソースの関連性。

・Seasar2の使い方を知るためにソースを読もうと思った人。
 →Seasar2のドキュメントとソースの関連性?
 →Diconファイルとソースの関連性。

 Seasar2のようなDIコンテナの場合、コンテナに依存しないコードを書くのが普通な
ので、どういう内容を書いたらいいのか(期待されているのか)が悩みどころですね。

 上に上げた中では、拡張のための情報がコミッタの方々のご協力を仰がないと難しい
気がしました。他のものも漏れなく書くのは大変だと思いますが、志は高くということ
で(^^;


-- 
 Jundo Ishikawa <jundo.ishikawa @ gmail.com>


seasar-javadoc メーリングリストの案内