初心者でもわかる!Javadocの意味と書き方【サンプルあり】
  • facebookページ
  • twitterページ
  • 2019.08.22

    初心者でもわかる!Javadocの意味と書き方【サンプルあり】

    Javadocとは?

    Javadocは簡単に説明すると、Java言語のソースコードから「プログラムについて説明するドキュメント」を生成する仕組みです。

    Javadoc用のコメントを記述すると、作ったプログラムに対するドキュメントをソースコードに埋め込んでくれます。

    言葉だけで説明しても理解が難しいと思うので、具体的なコードを出して詳しく説明していきます。

     

    例えば、値を2倍して結果を出力する以下のようなプログラムがあるとしましょう。

     

    ソースコードには処理とコメントが記述されています。

    コメントは、

    のように、スラッシュ(/)2つで書かれている部分です。

    スラッシュとアスタリスク(*)で囲んで、

    とも書けます。

     

    このソースコードに対して、コンピュータは以下の内容を読み取って処理します。

     

    1. クラスの名称は「JavadocTest」である
    2. 「JavadocTest」の中には、メソッド「main」と「double」がある
    3. 「main」は「String[] args」を受けて「void」を返す
    4. 「doubleFunc」は「int number」を受けて「int」を返す

     

    コンピュータは処理を読み取るものの、コメントに書かれている内容やメソッドの中身はプログラムによって異なるので見ていないんです。

    そこで、コンピュータに「このコメントはドキュメントに載せてね」と判断させるために用いられるのが「Javadoc用のコメント」になります。

    Javadocの概要
    • Javadocは、「プログラムについて説明するドキュメント」を生成する仕組み
    • Javadoc用のコメントを記述すると、ドキュメントにコメントを反映させられる

    Javadoc用のコメントの書き方

    Javadoc用のコメントは、具体的にどのように記述すればいいのか知りたいです。

    では、次にサンプルを見ながらコンピュータがどのように処理をするのか見ていきましょう。

    Javadoc用のコメントは、スラッシュ(/)とアスタリスク(*)2つで始まるように「/**」で記述します。

    これで、Javadoc用のコメントと認識されます。

     

    また、Javadoc用のコメントの中で「@」は特殊な記号として認識されます。

    「@author」と記述するとプログラムの制作者を意味し、「@version」と記述するとバージョンを意味するといった「Javadocタグ」が付けられます。

    その他にもさまざまな種類のJavadocタグがあるので、後ほどご説明しますね。

     

    Javadoc用のコメントを記述して、値を2倍して結果を出力するプログラムのソースコードを書き直すと、以下のようになります。

     

    Javadoc用のコメントを追加したこのソースコードに対して、コンピュータは以下の内容を読み取って処理をします。

     

    1. クラスの名称は「JavadocTest」である
    2. 「JavadocTest」は「Javadocのテスト用クラス」である
    3. 「JavadocTest」を作ったのは「ポテパンスタイル」である
    4. 「JavadocTest」のバージョンは「1.0.0」である
    5. 「JavadocTest」の中には、メソッド「main」と「double」がある
    6. 「main」は「String[] args」を受けて「void」を返す
    7. 「main」は「mainメソッド」である
    8. 「main」は「doubleメソッドに引数を渡して結果を出力する」メソッドである
    9. 「doubleFunc」は「int number」を受けて「int」を返す
    10. 「doubleFunc」は「doubleFuncメソッド」である
    11. 「doubleFunc」は「引数を2倍にして返す」メソッドである
    12. 「doubleFunce」は「整数値」を受け取る
    13. 「doubleFunc」は「引数を2倍した整数値」を返す

     

    以上のように、Javadocはソースコードから、

    • ソースコードの構造から機械的に読み取れるもの
    • 特定の書式で書かれたコメント

    の2つを自動で抽出してまとめたドキュメントです。

    このドキュメントを作成するときに使われるコマンド・プログラムとも言えます。

    Javadocタグの種類と意味

    Javadoc用のコメントの中には、「説明文」と「Javadocタグ」を記述することが可能です。

    Javadocタグには以下の種類と意味があります。

     

    Javadocタグ

     

    意味

     

    @author

     

    作成者について指定します

     

    @version

     

    バージョンについて指定します

     

    @see

     

    「関連項目」として外部リンクやテキストを表示、他のフィールドやメソッドなどへの参照リンクについて指定します

     

    @deprecated

     

    クラスやメソッドなどを「非推奨」として指定します

     

    @since

     

    導入されたバージョンを指定します。「@version」タグは現在のバージョン、「@since」タグはどのバージョンから導入されているかを表す点が異なります

     

    @param

     

    パラメータに関する説明を指定します

     

    @return

     

    戻り値に関する説明を指定します

     

    @throws(@exception)

     

    発生する可能性のある例外に関する説明を指定します

     

    {@link}

     

    Javadocタグ中で、文字列を表示する場所の中に参照リンクを表示する場合に指定します

     

    {@linkplain}

     

    「{@link}」タグと同じだが、「{@link}」の文字列がコードテキストに対して、「{@linkplain}」タグはプレーンテキストで表示されます

     

    Javadocドキュメントの作成方法

    Javadocコマンドを使用してソースコードからドキュメントを作成する場合、以下のように実行すればドキュメントが作成できます。

     

    作成が正常にできると、htmlという名前のディレクトリが作成され、ディレクトリ内に「index.html」というファイルがあります。

    Webブラウザで開いて内容を確認すると、以下のようなHTML形式のドキュメントが生成されます。

    Javadocの意味と書き方まとめ

    Javadocの意味と書き方をご紹介していきました。

    Javadocは、クラスやメソッドなど、Java言語の構成要素とその説明が対応づけられているため、多人数で開発をする場合などに役立ちます。

    また、Javadocはフォーマットが決まっており、メソッド全体についてのコメントを書くため 意味のない情報を書くことが少なくなります。

    Javadocが必要になったときは、ぜひこの記事を読んで有効活用してくださいね。

     



    優良フリーランス案件多数掲載中!
    フリーランスエンジニアの案件をお探しなら
    ポテパンフリーランス

    この記事をシェア

    • Facebookシェア
    • Twitterシェア
    • Hatenaシェア
    • Lineシェア
    pickup









    ABOUT US

    ポテパンはエンジニアと企業の最適なマッチングを追求する企業です。

    READ MORE