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

[Jundo Ishikawa]

JUNDUです。

　お疲れ様です。少し思いついたあたり、返信させていただきます。

06/07/31 に Hideaki Suzuki<suzuki ＠ uinet.or.jp> さんは書きました:
> ■やりかた
>
> ・MLで 『KPT ComponentDef』というようなタイトルでスレッドを作り、
>   みんなでそのJavadocの問題点、課題点を指摘しつつ見直していく。

　なんとなくですが、またファイル毎の細かな単位にはならないような気が
します。振り返り全体で１スレッド、またはこの後出てくるパターンごとに
１スレッドとかではいかがでしょう。

> ・Javadoc記述についてパターン化できるものについてはパターン化し、
>   Wiki上に、Seasar2の日本語Javadocパターン集を作る。
>
> ・類似クラス(インターフェース)は『〜Aware系』とか『Illegal〜Exception系』
>   とかパターンに名前をつけて、記述サンプルをWikiに記載する。

　このあたり、ちょっと私の考えは違いました。私の中ではWikiは全体に適用
可能な汎用化された内容を記述した方がいいのかなと思っていました。

　なので、〜Aware系など別パッケージには出てくることが少ない気がするので、
メールベースでやるのはどうでしょう。

　ここは、Wikiの位置づけが個人ごとに違うかもなので、全体で方針を合わせた
ら私もそれに従います(^^;

　パターン分けには、私も賛成です。ちょっと試しに分けてみました（添付）
まだ、他にもグループ分けの切り口があるかもしれません。

> ・<code><var>{@link 〜} などの使い方についてもWikiの記述を充実
>   させて、パターン化（名前を付ける？）と統一を図る。

　このあたりは、汎用化して他のパッケージにも適用できそうですね。例外
クラスの@seeの書き方とか、パターン化できそうな気がします。

> ・修正は、原則として、オリジナルの担当者が行う。(これは議論の余地あり？)

　パターンごとに担当を改めて分けるという方法もありますね。

> ・基本はみんなで見直すが、「日本語表現大臣(文部大臣?)」、「@see担当大臣」、
>   「@throws担当大臣」など、見直す切り口ごとに担当を決めて、チェック漏れを
>   防止する。 （これは微妙かなぁ…）

　うーん、出来ると効率的そうですが、最初は難しい気もしますね(^^;;

> ■見直す際の切り口
>
> ・内容の正確さ(想定する読者に誤解を与えない内容であるか？)
>     …想定される読者像をある程度絞り込む必要あり？
>     …Javaodcを読んで理解するために必要な前提となる知識や参考リンクを
>        とかをJavadocのトップページに載せたりとか…？
>     …そこまでやる必要はないかなぁ…とも思ったり

　想定する読者というのは、ずっと気になっていました。読者は、ある程度
あわせたほうが記述がブレ難い気もします。想定読者に縛られることは無い
のかもしれませんが、想定読者が欲しい情報が書けたかというチェックの意
味で使うとよい気がします。

> ・日本語の表現
>     …デスマ調…もとい、です/ます調になっているか？
>     …国語のテストで赤点にならないレベルになっているか？（特に自分 orz）

　私も… orz

> ・@seeの記述の適切さ
>     …例外クラスであれば、例外が発生するメソッドを記述するとか
>
> ・@throwsの記述の適切さ
>     …Wikiでは、「インターフェースで例外を記述するときは、実装クラス側で
>        スローする可能性のある例外をすべて記述します。」となっているが、
>        意外と守られていない可能性が… (特に自分… orz)
>
> ・@〜の記述順
>     …以前、[seasar-javadoc:72] 参考資料(タグの記述順) で自分が
>        「The Elements of Java Style」にあった内容を書いています。
>        これも、どこまで統一するか検討が必要かも？

　この辺は、全部やった方がいい気がします。内容と違って、機械的に出来る
ところですし。

> ・理解の参考となるWebサイトのURLの記述 (いらないかも…)

　ここは、想定読者次第という気がします。リンクの場合、リンク切れに対応
する方法も考える必要が出てきますね。

> なんかまとまってませんが…とりあえず、思いつくままに書いてみました。
> 「これはやりすぎでない？」という部分は、多々あるかと… (^^;;;
> Javadocにも、ある程度個性が出てた方が、オープンソースっぽいし…(^^;;;

　そうは言っても、可能な限り合わせたいですね。特にcontainerパッケージは、
S2コンテナの顔(?)ですし。　がんばった結果、それでもバラツキが出るのは、
仕方ないと思います。J2SE1.4のJavadocも結構バラツキがありますし(^^;;

> その他の見直しポイントや、やり方のアイデアなどありますか？

　今のところ思いついていたことは、全部 鈴木(belltree)さんに言われちゃい
ました(^^)


-- 
 Jundo Ishikawa <jundo.ishikawa ＠ gmail.com>
-------------- next part --------------
〓`Def〓n
AccessTypeDef
ArgDef
AspectDef
AutoBindingDef
BindingTypeDef
ComponentDef
InstanceDef
InterTypeDef
MetaDef
MethodDef
PropertyDef
InitMethodDef
DestroyMethodDef

〓`Def〓〓〓〓(^^;
TooManyRegistrationComponentDef

〓`Aware〓n
ArgDefAware
AspectDefAware
DestroyMethodDefAware
InitMethodDefAware
InterTypeDefAware
MetaDefAware
PropertyDefAware

〓R〓〓〓|〓[〓l〓〓〓g〓g〓〓〓〓〓〓〓n
ConstructorAssembler
MethodAssembler
PropertyAssembler

〓`DefRuntimeException〓n
IllegalAccessTypeDefRuntimeException
IllegalAutoBindingDefRuntimeException
IllegalBindingTypeDefRuntimeException
IllegalInstanceDefRuntimeException

〓w〓〓〓〓〓〓〓〓〓R〓〓〓|〓[〓l〓〓〓g〓g〓〓〓〓〓〓〓〓〓s〓〓〓O〓n
IllegalConstructorRuntimeException
IllegalAutoBindingPropertyRuntimeException
IllegalMethodRuntimeException

〓A〓m〓e〓[〓V〓〓〓〓〓s〓〓〓〓〓O〓n
IllegalInitMethodAnnotationRuntimeException
IllegalDestroyMethodAnnotationRuntimeException


〓〓〓〓〓A〓〓〓〓〓〓〓〓〓〓〓c〓B
ClassUnmatchRuntimeException
ComponentNotFoundRuntimeException
ContainerNotRegisteredRuntimeException
CyclicReferenceRuntimeException
ExtensionNotFoundRuntimeException
TooManyRegistrationRuntimeException

ContainerConstants

Expression

ExternalContext
ExternalContextComponentDefRegister

S2Container
ComponentDeployer