世界標準の「Java Docの書き方」。

Question

ecilpseで、Java doc を書いています。

さらにご指摘を下さい。2015/07/23

2015/07/23 追記
メソッドのJava Docの書き方をガラッと変えました。
すばらしい、出力結果の表示になり、とても読みやすくなります。

2015/07/27 追記
下記、ここでお聞きしたのやURL, Java Docのページ、eclispでエラーがでない逃げ方を
５０回くらい試して作った、Java Docの書き方ですが、

まだ、改善の余地が沢山あると思います。
間違っているとか、もっと情報をいれれるよとか、
変更履歴の入れ方など、ご指摘をください。

2015/07/28 追記
大手のコーディング規約を一通りしました。Oracleを含め、日本の大手企業。
下記が、一番ベストと判断します。

---

教科書どおり（＝どの教科書？）に、Java Docを書いていたのですが、
ecilpsで、出力すると、エラーやワーニングが全部にでて、
出力結果もぼろぼろでした。

elicpsの中に、ウィンドウ⇒設定⇒JAVA⇒コード・スタイル⇒コード・テンプレートで、
Java Docの形式を指定できます。

その設定をしおくと、クラス名やメソッド名の上で、ポップアップウィンドウで、
Java Docをそのまま記述してくれますので、手入力で必要なことを書き込むだけです。

その後、eclipsで、Java Docをエクスポートすると、
html形式で出力されます。

問題は、上記テンプレートは中途半場にJava Docのキーワードを含んでいるので、
全部使えるかと思って、それを書くと、出力時に、ワーニングやエラーになりNG。

そこで、
多数のホームページを参考にしつつ、eclipsのコード・テンプレートの設定でできるがエラーや警告がでると言った問題を、クリアした書き方を
つくりました。

変更履歴なども書きたいのですが、書こうとすると、
・Java Docへ表示されなかったり、
・余分なものだとワーニングやエラーがでます。

下記で、さらに eclips出力で、エラーやワーニングを出さずに、かつ、Java Docへ表示されるものなど、
改善できるところはありますでしょうか？

---

■ファイル最上部に書くJava Docの書き方
/**
*

• DBにアクセスするクラス。<br>
• その他、ごにょごにょ<br>
• <ul>
• <li>指定されたユーザID、パスワードが存在しない場合</li>
• <li>指定されたユーザアカウントが失効している場合</li>
• </ul>
• ${package_name}
• ${file_name}
• ${project_name}
• @since : 1.0 : 2015/05/01
• @author : mio.asakura
• Copyright (c) Mio Co.,Ltd.<br>

*/

補足１）変更履歴は、かけない。
補足２）バージョンは、書いてもJava Docへ出力されない。が、「@since : 1.0 : 2015/05/01」こう書けば、出力される。
補足３）「@since : 1.0」の書き方は、Java Docについて、まとめてあったサイトを見て書いてみたが、無駄だった。

---

■クラスのJva Docの書き方
/**
*

• 指定されたユーザID、パスワードで、DBのオープンを行なう。<br>
• オープンの結果をtrue/false で返す。<br>
• 以下の場合は、オープンエラーとなる。<br>
• <ul>
• <li>指定されたユーザID、パスワードが存在しない場合</li>
• <li>指定されたユーザアカウントが失効している場合</li>
• </ul>
• @since : 2015-05-01
• @author : mio.asakura

*/
public class DB_Package extends Object implements java.io.Serializable
{
省略
}

補足）これ以上、書けない。これ以上色々書くと、ワーニングがでる。

---

■コンストラクタのJava Docの書き方
/**
*
* 指定されたユーザID、パスワードで、DBのオープンを行なう。<br>
* オープンの結果をtrue/false で返す。<br>
* 以下の場合は、オープンエラーとなる。<br>
* <ul>
* <li>指定されたユーザID、パスワードが存在しない場合</li>
* <li>指定されたユーザアカウントが失効している場合</li>
* </ul>
*
* @since : 2015-05-01 / mio.asakura
*
*/
public DB_Package()
{
省略
}

補足１）「警告 - @author タグは constructor ドキュメント内では使用できません。使用できるのは次の種類のドキュメント内だけです: overview, package, class/interface。」

---

■メソッドのJava Docの書き方
/**
*
* 指定されたユーザID、パスワードで、DBのオープンを行なう。<br>
* オープンの結果をtrue/false で返す。<br>
* 以下の場合は、オープンエラーとなる。<br>
* <ul>
* <li>指定されたユーザID、パスワードが存在しない場合</li>
* <li>指定されたユーザアカウントが失効している場合</li>
* </ul>
*
* @since : 2015-05-01 / mio.asaka
*
* @param userId : int ユーザID
* @param password : String パスワード
*
* @return true の場合はオープン成功、false の場合はオープン失敗。
*
* @throws SQLException DBのオープンに失敗した場合。
*
*/
public boolean open(int userId, String password) {
省略
)

補足１）returnは、複数行書いても、１行目しかJava docへ出力されない。
補足２）returnは、カンマ区切りで、１行で書く。
補足３）「警告 - @author タグは method ドキュメント内では使用できません。使用できるのは次の種類のドキュメント内だけです: overview, package, class/interface」
補足４）パラメータが無いときは、@paramの行をかけない。void や Nothing と書くと、「警告 - @param の引数 "void" がパラメータ名ではありません。」となる。
補足５）戻り値が無いときは、@returnの行を書けない。

以上

Answer 1

すばらしい、Java Docの書き方を編み出したので、
自己完結します。

協力してくださったみなさま、ありがとうございました。

Answer 2

何を回答として得たいかイマイチはっきりしないので、回答不適切かもしれませんが。

変更履歴なども書きたいのですが、書こうとすると、
・Java Docへ表示されなかったり、
・余分なものだとワーニングやエラーがでます。

変更点はバージョン管理ツール（ＳＶＮ，ＧＩＴ）の類に任せるのが筋です。

/**
 *
 * explain : DBアクセスクラス
 * / class : DB_Package 

途中でコメント閉じてますね。これだとコンパイルエラーなきもしますが。

基本、JavaDocは@から始まるキーワードのみの構成で、Eclipseが{$***}をJavaDoc出力時に置換する
以外は特に変なことはしないはずです。

一度、落ち着いて見直すことをお勧めします。

Comments

[退会済みユーザー]

いえ、ここは「* / class」半角スペースを入れてあります。
表示時に、一行で、explainとclass名が/で区切られて、表示されます。

「変更点はバージョン管理ツール（ＳＶＮ，ＧＩＴ）の類に任せるのが筋です。」
なるほど、承知しました。
それで、変更履歴をかく、キーワードがJava Docには、ないのですね。
ありがとうございます。

[退会済みユーザー]

このJava Docの書き方は、前期にもありますが、Java Docのページ、各種参考サイト、過去のご指摘、eclipsで５０回以上実際にHTMLを吐き出して、エラーやワーニングを出さず、HTMLに、必要な情報が表示される書き方です。@がないところは、Java Docの基本の書き方で、そのままテキストを表示する書き方です。(Java Docのページに書いてある）。なので、これ以上、私には、改良作が見つからず、かといって、どうせ書くなら、eclipsで出力できる限界の、世界一の書き方で書きたいので、質問しています。

[tenraku]

--引用--
私には、改良作が見つからず、かといって、どうせ書くなら、eclipsで出力できる限界の、世界一の書き方で書きたいので、質問しています。
--引用ここまで--
通常のプロジェクトごとでいろいろあるとは思いますのでそれぞれです。と言ってしまうと終ってしまうので、補足についていくつか回答します

ファイル上部
補足２）バージョンは、書いてもJava Docへ出力されない。が、「@since : 1.0 : 2015/05/01」こう書けば、出力される。
A.@Sinceは対応開始バージョンの表記。＠VersionはJavaDocコマンドに引数指定で出力できる
さらに、ファイル上部はあまり記載することはない筈です。（単一ファイル単一クラスが普通の設計になるため）

クラスについて
補足）これ以上、書けない。これ以上色々書くと、ワーニングがでる。
A.テンプレートとしては内容を書く旨を記載しておいたほうが良いです。内容については、”このクラスは何を表現しているか”です。何をするかは不要。といった旨を

コンストラクタについて
補足１）「警告 - @author タグは constructor ドキュメント内では使用できません。使用できるのは次の種類のドキュメント内だけです: overview, package, class/interface。」
A.基本的にファイル単位で責任者、担当者を振ることを想定しているためです。

JavaDocは、プログラム設計時の成果物みたいなものだと思うので、自分がメンテナンスするときにあると良いなと思う情報を残せればよいものだと思うのです。
公式のJavaAPIのソースに書いてあるJavadocがおそらく世界で一番とまでも行きませんが、お墨付きがあるJavaDocだと思いますので参考に見て考えていただいたほうが良いかと思います。

[swordone]

すみません，どうしても気になったので指摘させていただきます．
"eclipse"です．最後の"e"が抜けてます．

[退会済みユーザー]

いえいえ、細かいところほど、自分ではきづかないので、
ご指摘が必要な場所です。
どんどん、ご指摘願います。
ありがとうございました。