日本語でのJavaDocの書き方

JavaDocを何で書くの?とか、書き方とかをまとめたページはたくさんありますが、日本語特有の情報が抜け落ちていたり、英語でのJavaDocの書き方を説明するものばかりなので、日本語特有の情報をいくつか書きたいと思います。

なお、JDK 8u144あたりでの挙動です。将来では変わるかもしれません。

JavaDocの書き方の一般的なものを知りたい場合は公式のマニュアルを見るのが一番良いと思います。
https://docs.oracle.com/javase/jp/8/docs/technotes/tools/windows/javadoc.html

サマリー文の後は2つ改行を入れましょう。

/**
 * 一行目はサマリー文としてその処理(クラス、メソッド等)の概要として扱われます。
 *
 * <p>英語では行末に「.」(ピリオド)が入り、JavaDocではピリオドまでを1行目のサマリーとして扱うという処理が入っていますが、
 * 日本語では基本的にピリオドは使用しませんが、「。」も区切り文字として認識してくれるようです。
 * <p>なお、この挙動についてはJavaDocのマニュアルには書いてありません。
 * <p>さらに、マニュアルに書いてない挙動としては、ピリオドの後に空白行が続いたとしてもその後に小文字が続く場合は文末として認識されないようです。
 * 英語の場合は文頭に小文字が来る場合がないからなのでしょうね。
 * 必ず改行させるために2行目には空行を入れておくと良いでしょう。

また、サマリー行の次の行では<p>タグから開始することを推奨します。そちらのほうがサマリーと明確に分かれるのできれいです。
https://github.com/megascus/servlet-spec/blob/translation/src/main/java/javax/servlet/Servlet.java#L98
https://megascus.github.io/servlet-spec/docs/apidocs/javax/servlet/Servlet.html#init-javax.servlet.ServletConfig-
https://github.com/megascus/servlet-spec/blob/translation/src/main/java/javax/servlet/Servlet.java#L124
https://megascus.github.io/servlet-spec/docs/apidocs/javax/servlet/Servlet.html#getServletConfig--

@Throwsには〜の場合と書きましょう。

英語の場合は
@Throws Exception if〜〜
と書くのが良いとされていますが、日本語の場合は
@Throws Exception 〜〜の場合
と書くのがしっくりきました。(Servlet API 4.0を翻訳しての感想)

ですます調で書きましょう。

ドキュメントは誰かに読んでもらうものです。
できる限り丁寧な言葉づかいで書いたほうが喜ばれます。
断定調だと高圧的な感じになってしまいますし、なんかさー、とか、適当な口語をつかわれると読んでてだるいと感じるわけよ。

日本語固有の話ではないけれども

用語は統一しましょう。

例えば、Servlet 4.0のAPIでは以下の用語が同じ意味として使用されていました。

  • Web Server
  • Servlet Container
  • Web Container

判ってる人は同じ物だってわかるけど、初めての人には優しくないですよね。

typoには気をつけよう

Javaを書くためのエディタで日本語を書かなければいけない都合上typoがすごい多くなりやすいです。
MS Wordに一度食べさせる等をして、typoを発見できるように努めるのも良いでしょう。

まとめ

JavaDoc書くのは面倒くさいですが、マニュアルがない製品を使うのが辛いように、JavaDocは書いただけの見返りをAPIの使用者に与えてくれます。
がんばって書きましょう。