what is javadoc how use it generate documentation
このチュートリアルでは、JavaDocツールとJavaDocコメント、およびコードドキュメントを生成する方法について説明します。
JavaDocは、JDKにパッケージ化されている特別なツールです。これは、JavaソースコードのコードドキュメントをHTML形式で生成するために使用されます。
これは、Sun Microsystems（現在のOracle Corporation）のJava言語用のドキュメントジェネレータです。
=> ここですべてのJavaチュートリアルを確認してください。
学習内容：
JavaDocとは
このツールは、「ドキュメントコメント」形式を使用してJavaクラスをドキュメント化します。 Eclipse、IntelliJIDEA、NetBeansなどのIDEには、HTMLドキュメントを生成するためのJavaDocツールが組み込まれています。また、プログラマーがJavaDocソースを作成するのに役立つ多くのファイルエディターが市場に出回っています。
ソースコードのドキュメントとは別に、このツールは、Javaアプリケーションの構造を分析するために使用する「ドックレット」と「タグレット」を作成するAPIも提供します。
注意すべき点の1つは、コンパイラがJavaプログラムのコンパイル中にすべてのコメントを削除するため、このツールがアプリケーションのパフォーマンスに影響を与えることはないということです。
プログラムにコメントを書き込んでから、JavaDocを使用してドキュメントを生成することは、プログラマー/ユーザーがコードを理解するのに役立ちます。
JavaDocによって生成されるHTMLドキュメントはAPIドキュメントです。宣言を解析し、ソースファイルのセットを生成します。ソースファイルには、フィールド、メソッド、コンストラクター、およびクラスが記述されています。
ソースコードでJavaDocツールを使用する前に、プログラムに特別なJavaDocコメントを含める必要があることに注意してください。
コメントに移りましょう。
JavaDocコメント
Java言語は、次のタイプのコメントをサポートします。
＃1）単一行コメント： 単一行コメントは「 // 」とコンパイラがこれらに遭遇すると、行の終わりまでこれらのコメントに続くすべてを無視します。
＃2）複数行コメント： 複数行コメントは、「 /*….*/ 」。したがって、「/ *」シーケンスに遭遇すると、コンパイラは、終了シーケンス「* /」に遭遇するまで、このシーケンスに続くすべてを無視します。
＃3）ドキュメントのコメント： これらはドキュメントコメントと呼ばれ、APIドキュメントを生成するためにツールによって使用されます。ドキュメントのコメントは「 /** ドキュメンテーション */ 」。ご覧のとおり、これらのコメントは上記の通常のコメントとは異なります。後で説明するように、ドキュメントコメントにはHTMLタグが含まれている場合もあります。
jiraダッシュボードの作成方法
したがって、このツールを使用してAPIドキュメントを生成するには、プログラムでこれらのドキュメントコメント（ドキュメントコメント）を提供する必要があります。
JavaDocコメントの構造
JavaのDocコメントの構造は、docコメントの開始タグに追加のアスタリスク（*）があることを除いて、複数行コメントに似ています。したがって、ドキュメントコメントは「/ *」ではなく「/ **」で始まります。
さらに、JavaDocスタイルのコメントにはHTMLタグを含めることもできます。
JavaDocコメント形式
ドキュメント化するプログラミングコンストラクトに基づいて、クラス、メソッド、フィールドなどのコンストラクトの上にドキュメントコメントを配置できます。各コンストラクトのドキュメントコメントの例を見ていきましょう。
クラスレベルのフォーマット
クラスレベルのドキュメントコメント形式は、次のようになります。
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } 上に示したように、クラスレベルのドキュメントコメントには、クラスの作成者、リンクがある場合など、すべての詳細が含まれます。
メソッドレベルのフォーマット
以下に、メソッドレベルでのドキュメント形式の例を示します。
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } 上記の例からわかるように、メソッドのdocコメントには任意の数のタグを含めることができます。コメントの説明の中に、で示される段落を含めることもできます。
..。
。メソッドの戻り値（@return）とパラメーター（@param）を説明する特別なタグもあります。
フィールドレベルのフォーマット
次の例は、フィールドのドキュメントコメントを示しています。
/** * The public name of a message */ private String msg_txt;上記の例からわかるように、タグなしでプレーンコメントを付けることもできます。 JavaDocコマンドでプライベートオプションを指定しない限り、JavaDocはプライベートフィールドのドキュメントを生成しないことに注意してください。
次に、ドキュメントのコメントで使用されるタグについて説明します。
初心者のためのコンピュータをプログラムする方法
JavaDocタグ
Javaには、ドキュメントコメントに含めることができるさまざまなタグが用意されています。これらのタグを使用すると、ツールはこれらのタグを解析して、ソースコードから適切にフォーマットされたAPIを生成します。
各タグでは大文字と小文字が区別され、「@」記号で始まります。上記の例からわかるように、各タグは行の先頭から始まります。それ以外の場合、コンパイラはそれを通常のテキストとして扱います。慣例として、同じタグが一緒に配置されます。
ドキュメントコメントで使用できるタグには2つのタイプがあります。
＃1）ブロックタグ ：ブロックタグの形式は @タグ名 。
ブロックタグはタグセクションに配置でき、主な説明に従います 。
＃2）インラインタグ ：インラインタグは中括弧で囲まれ、次の形式になっています。 {@タグ名} 。インラインタグは、ドキュメントコメント内のどこにでも配置できます。
次の表に、ドキュメンテーションコメントで使用できるすべてのタグを示します。
| 鬼ごっこ | 説明 | に適用されます |
|---|---|---|
| @returnの説明 | 戻り値の説明を提供します。 | 方法 |
| @author xyz | クラス、インターフェイス、または列挙型の作成者を示します。 | クラス、インターフェイス、列挙型 |
| {@docRoot} | このタグには、ドキュメントのルートディレクトリへの相対パスがあります。 | クラス、インターフェイス、列挙型、フィールド、メソッド |
| @バージョンバージョン | ソフトウェアバージョンエントリを指定します。 | クラス、インターフェイス、列挙型 |
| @ sincesince-text | この機能がいつ存在するかを指定します | クラス、インターフェイス、列挙型、フィールド、メソッド |
| @リファレンスを参照 | 他のドキュメントへの参照（リンク）を指定します | クラス、インターフェイス、列挙型、フィールド、メソッド |
| @param名の説明 | メソッドのパラメータ/引数を説明するために使用されます。 | 方法 |
| @exceptionクラス名の説明 | メソッドがコードでスローする可能性のある例外を指定します。 | 方法 |
| @throwsクラス名の説明 | ||
| @非推奨の説明 | メソッドが古くなっているかどうかを指定します | クラス、インターフェイス、列挙型、フィールド、メソッド |
| {@inheritDoc} | 継承の場合にオーバーライドされたメソッドから説明をコピーするために使用されます | オーバーライド方法 |
| {@リンク参照} | 他のシンボルへの参照またはリンクを提供します。 | クラス、インターフェイス、列挙型、フィールド、メソッド |
| {@linkplainリファレンス} | {@link}と同じですが、プレーンテキストで表示されます。 | クラス、インターフェイス、列挙型、フィールド、メソッド |
| {@value #STATIC_FIELD} | 静的フィールドの値を記述します。 | 静的フィールド |
| {@codeリテラル} | {@literal}のようなコードフォントでリテラルテキストをフォーマットするために使用されます。 | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } JavaDocを生成するためにプログラムやプロジェクトをコンパイルする必要がないことはわかっています。 IntelliJIdea Ideは、ドキュメントを生成するための組み込みツールを提供します。 IntelliJIdeaを使用してドキュメントを生成するには、以下の手順に従います。
- 「ツール」->「JavaDocの生成」をクリックします
- JavaDocツールをクリックすると、次の画面が開きます。
ここでは、プロジェクト全体のドキュメントを生成するか、1つのクラスのみを生成するかなどを指定できます。また、ドキュメントファイルが生成される出力ディレクトリを指定することもできます。上図に示すように、他にもさまざまな仕様があります。
すべてのパラメータを指定したら、(OK)をクリックします。
- これで、出力ウィンドウにJavaDoc生成プロセスが表示されます。サンプルのJavaDoc出力ウィンドウは次のようになります。
- 生成が完了すると、次のファイルが生成されます。
- Mainクラスを指定すると、ファイルMain.htmlが生成されます。 index.htmlもMain.htmlと同じ内容であることに注意してください。
- help-doc.htmlファイルには、Javaエンティティの一般的な定義が含まれています。このファイルの内容のサンプルを以下に示します。
- 同様に、以下はMain.htmlファイルのサンプルコンテンツです。
したがって、これは、IntelliJアイデアでこのツールを使用してドキュメントを生成できる方法です。 EclipseやNetBeansなどの他のJavaIDEでも同様の手順を実行できます。
よくある質問
Q＃1）JavaDocの用途は何ですか？
回答： JavaDocツールにはJDKが付属しています。これは、JavaソースコードのコードドキュメントをHTML形式で生成するために使用されます。このツールでは、ソースコード内のコメントが/**….*/のように事前定義された形式で提供されている必要があります。これらはドキュメントコメントとも呼ばれます。
Q＃2）Javaドキュメントの例は何ですか？
回答： Java DocドキュメントツールはHTMLファイルを生成するため、Webブラウザからドキュメントを表示できます。 JavaDocドキュメントの実際の実例は、Oracle Corporation（http://download.oracle.com/javase/6/）のJavaライブラリのドキュメントです。 ドキュメント /火/。
Q＃3）プライベートメソッドにはJavaDocが必要ですか？
回答： いいえ。プライベートフィールドとメソッドは開発者専用です。エンドユーザーがアクセスできないプライベートメソッドまたはフィールドのドキュメントを提供するロジックはありません。 Java Docは、プライベートエンティティのドキュメントも生成しません。
例を含むUNIXシェルスクリプトコマンド
Q＃4）JavaDocコマンドとは何ですか？
回答： このコマンドは、Javaソースファイル内の宣言とドキュメントコメントを解析し、パブリッククラスと保護クラス、ネストされたクラス、コンストラクタ、メソッド、フィールド、およびインターフェイスのドキュメントを含む対応するHTMLドキュメントページを生成します。
ただし、JavaDocは、プライベートエンティティおよび匿名内部クラスのドキュメントを生成しません。
結論
このチュートリアルでは、JavaソースコードのコードドキュメントをHTML形式で生成するのに役立つJDKにパッケージ化されたJavaDocツールについて説明しました。コマンドツールを介してJavaDocコマンドを実行するか、ほとんどのJava IDEで使用可能な組み込みのJavaDoc機能を使用して、ドキュメントを生成できます。
IntelliJIdea JavaIDEでツールを使用してドキュメントを生成する方法を見てきました。チュートリアルでは、ドキュメントコメントで使用できるさまざまなタグについても説明しました。これにより、ツールは、ソースコードに関連するすべての情報を詳述したユーザーフレンドリーなドキュメントを生成できます。
=> ゼロからJavaを学ぶには、ここにアクセスしてください。