質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

90.61%

  • Java

    13528questions

    Javaは、1995年にサン・マイクロシステムズが開発したプログラミング言語です。表記法はC言語に似ていますが、既存のプログラミング言語の短所を踏まえていちから設計されており、最初からオブジェクト指向性を備えてデザインされています。セキュリティ面が強力であることや、ネットワーク環境での利用に向いていることが特徴です。Javaで作られたソフトウェアは基本的にいかなるプラットフォームでも作動します。

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

解決済

回答 2

投稿 編集

  • 評価
  • クリップ 0
  • VIEW 11K+
退会済みユーザー

退会済みユーザー

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の行を書けない。
--------------------------------------------------------------------------


以上
  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 2

0

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

変更履歴なども書きたいのですが、書こうとすると、
・Java Docへ表示されなかったり、  
・余分なものだとワーニングやエラーがでます。 
変更点はバージョン管理ツール(SVN,GIT)の類に任せるのが筋です。

/**
 *
 * explain : DBアクセスクラス
 * / class : DB_Package 
途中でコメント閉じてますね。これだとコンパイルエラーなきもしますが。

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2015/07/27 14:38

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

    「変更点はバージョン管理ツール(SVN,GIT)の類に任せるのが筋です。」
    なるほど、承知しました。
    それで、変更履歴をかく、キーワードがJava Docには、ないのですね。
    ありがとうございます。

    キャンセル

  • 2015/07/27 17:50

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

    キャンセル

  • 2015/07/27 18:29

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

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

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

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

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


    キャンセル

  • 2015/07/28 09:30

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

    キャンセル

  • 2015/07/30 08:53

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

    キャンセル

check解決した方法

-9

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 90.61%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る

  • Java

    13528questions

    Javaは、1995年にサン・マイクロシステムズが開発したプログラミング言語です。表記法はC言語に似ていますが、既存のプログラミング言語の短所を踏まえていちから設計されており、最初からオブジェクト指向性を備えてデザインされています。セキュリティ面が強力であることや、ネットワーク環境での利用に向いていることが特徴です。Javaで作られたソフトウェアは基本的にいかなるプラットフォームでも作動します。