JavaDocについて

Java

JavaDocを納品することになってしまった。納品先が海外なのでコメントは英語でと当初から決まりがあったものの、明確に納品物と指定されていたわけではなく、また英語でコメント書くのはやっぱり難しかったということもあってなんとも使えなさそなJavaDocが生成される…。

いまさらながらJavaDocについての知識を仕入れる。

Effective Java isbn:4894714361 の項目28より気づいたとこだけ

    • @throwsの説明は単語「if」からはじめ条件を名詞句で記述する。
    • メソッドやコンストラクタの概要説明は動詞句で記述する。
    • クラス、インタフェース、フィールドの概要説明は名詞句で記述する。

あんまり実践できてない。



The Element of Java Style isbn:0521777682の40と41の項目

    • 概要説明（summary-description）をパッケージごとにをつくる。package.htmlをパッケージのディレクトリにソースと一緒に置いておく。
    • 概要説明（summary-description）はアプリケーションに対してもつくる。javadocの-overviewを使って引数渡す。

これって知りませんでした。常識？

マニュアルにちゃんと載っている。

packageのグルーピングもできるみたい。そういえばGroovyのJavaDocって二段に分かれていてなんで？って思ったっけ。これがきっとそうに違いない。

あとthisって単語はそのクラスのinstanceを指すときに使うらし。