ecilpseで、Java doc を書いています。
さらにご指摘を下さい。2015/07/23
2015/07/23 追記
メソッドのJava Docの書き方をガラッと変えました。
すばらしい、出力結果の表示になり、とても読みやすくなります。
2015/07/27 追記
下記、ここでお聞きしたのやURL, Java Docのページ、eclispでエラーがでない逃げ方を
50回くらい試して作った、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>
*/
補足1)変更履歴は、かけない。
補足2)バージョンは、書いてもJava Docへ出力されない。が、「@since : 1.0 : 2015/05/01」こう書けば、出力される。
補足3)「@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()
{
省略
}
補足1)「警告 - @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) {
省略
)
補足1)returnは、複数行書いても、1行目しかJava docへ出力されない。
補足2)returnは、カンマ区切りで、1行で書く。
補足3)「警告 - @author タグは method ドキュメント内では使用できません。使用できるのは次の種類のドキュメント内だけです: overview, package, class/interface」
補足4)パラメータが無いときは、@paramの行をかけない。void や Nothing と書くと、「警告 - @param の引数 "void" がパラメータ名ではありません。」となる。
補足5)戻り値が無いときは、@returnの行を書けない。
以上
回答2件
あなたの回答
tips
プレビュー
バッドをするには、ログインかつ
こちらの条件を満たす必要があります。