Javadoc仕様の概要

はじめに:

javadoc が JDK に埋め込まれていることはわかっているので、javadoc 仕様に従うことが Java アノテーションの正統性であることは間違いありません。 javadoc は非常に実用的です。

(学習ビデオ共有: java ビデオ チュートリアル)

1. コメントとは

コメントはコードを作成するためのものですもっと読む 読みやすく、チームワークのコミュニケーションコストを削減します。チームでは、コードがより明確で読みやすく、より標準化されていれば、より多くの人々と互換性を保つことができるため、昇進と昇給は確実にあなたのものになります。
少し前にこんな格言を聞いたことがあります。「自分のコードさえ理解できれば、あなたは必要不可欠な人物だ」ということです。これを言った人は愚かです。彼が書いたコードを読んで理解できるのは彼だけです。誰も彼に会いたがりません。彼は孫のように暮らしています。誰もが孫を必要としていますか?

2. よく使用されるコメントのショートカット キー

行をコメントする: //行の内容です
ショートカット キー: ctrl/逆の操作: ctrl/ブロックをコメントする:/ *私はブロックの内容です* /
ショートカット キー: Ctrl SHIFT / 逆操作: CTRL SHIFT \javadoc 認識可能なコメント:

	/**
	 * 我是注释
	 * 我也是注释
	 * 我还是注释，我们都能被javadoc识别
	 */

3, javadoc 仕様

Javadoc 仕様に従ってくださいでは、javadoc コマンドを使用できます。非常に直感的で読みやすい API ドキュメントを生成するのに非常に便利です。
プログラム中に登場するコメントは、意識的には自分が見るための単純なコメントと、読みやすい文書を生成することを目的としたjavadoc仕様に準拠したコメントの2種類に分けることができます。 。
生成された API ドキュメントをよく読んでください。図に示すように、説明が必要な部分が 3 つあります。

##上の赤枠の内容はすべて私が追加したコメントです。単純な Hello クラスです。ソースコードは次のとおりです。興味のある方は、ご自身で試してみてください:

/**
  *	@author XXXX
  *	@version 创建时间：2021年1月21日 下午3:22:01
  *	
  */
public class Hello {

	/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}
	
	/**
	 * havaReturn方法就是为了测试javadoc注释规范的.
	 * <p>我发现只有有返回值的方法才可以使用return标签<br>
	 * 没有return硬是要用，只会在javadoc时候报错
	 * @param a 输入的第一个int类型的参数
	 * @param b 输入的第二个int类型的参数
	 * @return add 两个数的和运算结果
	 */
	public int haveReturn(int a,int b){
		int add=0;
		add=a+b;
		return add;
	}

}

注意すべき点がいくつかあります:

API ドキュメントに作成者とバージョンを表示したい場合は、プログラムのコメントに @author と @version を追加するだけでなく、プログラム内の複数の場所で @author の注釈を付けても、最終ドキュメントでは 1 回だけ表示されることに注意してください。コメントは 1 回のみにすることをお勧めします)、コンパイル時に dos コマンドでも指摘します:

javadoc -d directory -version -author Hello.java
ここで、-d フォルダーは、生成された API ドキュメント (実際には (構成された) 多くの Web ページ) をフォルダー フォルダーに配置することを意味します。もちろん、フォルダーはパスにすることもできます。メソッドの概要とメソッドの詳細を区別するには?

/**
	 * main()方法简述(后面这个dot必不可少).
	 * <p>这就是为了测试注释<br>
	 * 没什么好说明的，只为了说明能出现在这里
	 * @param args 就是系统配的，没啥说的
	 * 
	 */
	public static void main(String[] args) {
//		 TODO Auto-generated method stub
		System.out.println("hello");	

	}

メソッドに関するコメントがたくさんあることに気づいたと思いますが、javadoc はどのようにして概要を抽出するのでしょうか?そうです、1 つのドット (.) に頼って、私のコメントで言及されているドットを観察してください。これが概要を抽出するための鍵です。ドットの前に概要があり、すべてが詳細な紹介になっています (詳細な紹介には概要が含まれています) )

生成されたドキュメント内のコメントの組版を制御する方法

プログラムで制御できるのはコメントの組版ですが、この組版は javadoc では認識されません。Javadoc はコメントの行を検索し、 * とスペースを削除します。先ほど渡して、生成されたドキュメントが HTML タイプであることに気付きました。そのため、プログラム内で HTML 構文をコメントする限り、API ドキュメント形式を編集できます。段落などの単純な HTML 構文を使用するだけなので、難しすぎます。

、改行
これらで十分です。結局のところ、コメントはそれほど長くなりません。

@paramパラメータ1の説明(形式に注意)

@return 戻り値の説明(形式に注意)

戻り値がある場合は記述、戻り値がない場合value, you don't need to write it. If you write it, it will be Error reports

実際、クラス コメントとメソッド コメントの記述は非常に簡単です。クラスの前に /** と入力して、メソッドを選択して Enter キーを押すと、システムが自動的に追加し、システムがその追加方法を変更できます

新しいファイルの作成時に表示されるコンテンツを変更する方法、以下に自動的に完成するコメントを作成する方法私たちのコントロール (やるべきこと)

これを標準クラス ファイルから確認します。

out が次の属性 (フィールド) であることは誰もが知っています。 PrintStream 型の System クラスです。PrintStream クラスには多くのメソッドが定義されています。これらは当然 out メソッドなので、 out を定義するときは、その前のコメントに @see がたくさんあります。これが最適な場所です。 @see アノテーションを使用することをお勧めします。クラスのフィールドを定義するとき、フィールドが複合型 (特にカスタム複合型) の場合は、@see に注意してください。これには 2 つの利点があります。図を参照してください。 ＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃＃

これら 2 つの図はご存知かと思いますが、1 つ目は、プログラムを作成するときにカーソルを置いたときに表示されるプロンプトです。Javadoc 仕様に従ってコメントを記述すると、プログラムには、次のような非常に役立つプロンプトも表示されます。 2つ目は、Java8 APIドキュメントのStringクラスのoutフィールドの詳細な記述ですが、これも@seeさんのクレジットですが、@seeさんが書かれており、ご自身のプロジェクトのAPIドキュメントにもこのようなアノテーションがあります。

関連する推奨事項: Java 入門チュートリアル

以上がJavadoc仕様の概要の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。