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

[Koichi Kobayashi]

小林 (koichik) です．

Date:    Mon, 29 May 2006 10:55:32 +0900
From:    Momotaro Nishiumi <info ＠ momo-lab.net>
To:      seasar-javadoc ＠ ml.seasar.org
Subject: [seasar-javadoc:74] Re: ツッコミ大歓迎! 叩き台サンプル

> * ある程度で改行を入れてもらった方が、読みやすいかと思います。

これはフォーマッタが勝手にやるのであまり気にしないことに
しましょう．
Eclipse のフォーマッタはあまり嬉しくない整形をすることが
多くて，日本語というか (いわゆる) 倍角も 1 文字と数える
ような気のせいがします．
そのため，1 行の文字数を 80 文字にしている S2 の場合，
かなり横に長い行に整形されます．

ともあれ (JW)，Javadoc はソース上より HTML で読むのが
主なので整形はあまり気にしすぎないようにしましょう．

> * 半角文字の前後の空白は入れないルールだと思います。
>   何箇所か、<code>の前に空白があるようでした。

これもフォーマッタの影響かもしれません．
最初に

 * この辺に文章があって改行
 * <code>null</code>とかなんとか

みたいに書いてフォーマットすると，

 * この辺に文章があって改行 <code>null</code>とかなんとか

のように整形される場合があります．
これも個人的にはあまり気にしすぎても進まないと思うのですが，
気になるようならフォーマット後に見直すのをルールにします？

> * <p>を段落区切り文字として使うのはあまりよくなさそうです。
>   段落を<p>〜</p>で囲った方がHTMLとしてはよいのではないでしょうか。

これは同意．
是非 <p>〜</p> で．

> * 何箇所か、リテラルだと思われる部分が<code>で囲んでいませんでした。
>   > ...Beanプロパティ(getter/setter)によるアクセスを表します。...
>   の「Bean」「getter」「setter」あたりでしょうか。

これらはリテラルではなく単なる英語の表記だと思われ．
getter/setter はマークアップするなら <var>〜</var> とか．


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