[seasar-javadoc:17] Re: ガイドライン

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Thu, 25 May 2006 03:23:04 +0900
From:    Hideaki Suzuki <suzuki ＠ uinet.or.jp>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:16] Re: はじめまして＆宜しくお願いします

> > 特に異論がないようであれば，org.seasar.framework.container
> > あたりから 1 パッケージずつみんなで進めていきたいと
> > 思ってます．
> 賛成です。パッケージ毎に書き方をそろえながら書いていけば、
> JavaDocのパッケージのページなどに統一感が出ると思います。

1 票ゲット！！

> あと、ざっくりとしたガイドラインがあると最後までブレずに統一感のある
> ドキュメントになるかと思います。

一応 Seasar Wiki の Javadoc Project ページに少しあります．

http://www.seasar.org/wiki/index.php?SeasarJavadocProject

> たとえば・・・
>   ・日本語の書き方（です・ます調とか）

これは「です・ます調」で．

>   ・HTMLタグの使い方

リテラルは <code> で囲みたいですね．
# {@code } は Java5 からなので Seasar2 では使用禁止．
# S2-Tiger は可．

他に <ul> や <ol>，<table> なども駆使して．(^^;
個人的には {@link } が大好きです (笑)．

>   ・記述のポイント（目的、機能、関連する機能、など）

まずは

・Javadoc は仕様を書くもの

ということで，目的と使い方が分かるように書くところから
でしょうか．

>   ・サンプル（お手本とするオープンソースのプロダクトやクラス、フィールド、
>     メソッド用のテンプレートなど）

基本は Java (Java SE/EE) 自身の Javadoc ですね．
他では．．．
Spring の Javadoc は量が多すぎてちょっとなんだかなぁと
思うことしばし．
必要なことはしっかり書いて，それでいて簡潔なのがいいなぁ．

> 私自身、正直、真剣にJavaDocを記述したことが少ないので（オイオイ^_^;;;）
> 素人考えですが、いかがでしょう。
> ただ、準備に時間を掛け過ぎて、本作業が遅れないようにしないとですね…

そうですね，書いてみないと分からないことも多いと思うので，
少しずつ書いてからすりあわせしていきましょう．

> P.S. JavaDoc関係で良い本を知っている方がいたら教えて下さい。

古典 (？) としては

「The Elements of Java Style (isbn0-521-77768-2)」

でしょうか．
他によいものがあればコメントお願いします．

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