Einführung in die Javadoc-Spezifikation

Einführung:

Wir wissen, dass Javadoc in das JDK eingebettet ist, daher ist die Einhaltung der Javadoc-Spezifikation definitiv die Orthodoxie von Java-Annotationen. Es ist sehr praktisch, Javadoc zu haben, um die API-Dokumentation zu erstellen.

(Lernvideo-Sharing: Java-Video-Tutorial)

1 Was sind Kommentare?

Kommentare sollen den Code lesbarer machen und den Kommunikationsaufwand für die Teamarbeit reduzieren. Wenn Ihr Code in einem Team klarer, lesbarer und standardisierter ist, werden Beförderung und Gehaltserhöhung definitiv Ihnen gehören, da Sie mit mehr Menschen kompatibel sein können.
Ich habe vor einiger Zeit ein Sprichwort gehört: Wenn du nur deinen Code verstehen kannst, dann bist du die unverzichtbare Person. Die Person, die das gesagt hat, ist dumm. Nur er kann den Code verstehen, den er schreibt. Er lebt wie ein Enkel.

2. Häufig verwendete Tastenkombinationen für Kommentare

Eine Zeile kommentieren: //Ich bin der Inhalt der Zeile
Tastenkombination: Strg+/ Umgekehrte Operation: Strg+/Einen Block kommentieren: /*Ich bin der Inhalt des Blocks*/
Tastenkombination: Strg+Umschalt+/ Umgekehrte Bedienung: Strg+Umschalt+Javadoc Erkennbare Kommentare:

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

3. Javadoc-Spezifikation

Gemäß der Javadoc-Spezifikation können wir den Befehl javadoc verwenden, um einen sehr intuitiven und leicht lesbaren Text zu generieren API-Dokument, was sehr praktisch ist.
Die Kommentare, die wir im Programm erscheinen, können bewusst in zwei Arten unterteilt werden: Zum einen handelt es sich um einfache Kommentare zum eigenen Lesen und zum anderen um Kommentare, die der Javadoc-Spezifikation entsprechen und dem Zweck dienen, leicht lesbare Dokumente zu erstellen.
Lesen Sie das generierte API-Dokument sorgfältig durch, wie im Bild gezeigt:

Der Inhalt des roten Felds oben sind die Kommentare, die ich hinzugefügt habe Eine einfache Hallo-Klasse. Der Quellcode lautet wie folgt. Wenn Sie interessiert sind, können Sie es selbst ausprobieren:

/**
  *	@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;
	}

}

Es gibt einige Punkte, auf die hingewiesen werden muss:

Wenn Sie möchten, dass der Autor und die Version angezeigt werden Im API-Dokument müssen Sie nicht nur @author und @version in die Programmkommentare einfügen (es ist zu beachten, dass im Programm mehr vorhanden sind). Der @author-Kommentar an dieser Stelle wird im endgültigen Dokument nur einmal angezeigt. Ich empfehle, ihn nur zu kommentieren einmal) und weisen Sie auch während der Kompilierung im DOS-Befehl darauf hin:
javadoc -d Ordner -Version -Autor Hallo.java
wobei -d Ordner bedeutet, dass Sie das generierte API-Dokument (das tatsächlich aus vielen Webseiten besteht) in einem ablegen Ordnerordner. Natürlich kann der Ordner auch ein Pfad sein. Wie unterscheidet man zwischen Methodenzusammenfassung und Methodendetails?

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

	}

Sie müssen festgestellt haben, dass es viele Kommentare zu Methoden gibt. Wie extrahiert Javadoc die Zusammenfassung? Das ist richtig, verlassen Sie sich einfach auf einen Punkt (.), beachten Sie den in meinem Kommentar erwähnten Punkt, der der Schlüssel zum Extrahieren der Zusammenfassung ist. Dem Punkt steht die Zusammenfassung, und alles ist eine detaillierte Einführung (die detaillierte Einführung enthält die Zusammenfassung). )

So steuern Sie die Formatierung von Kommentaren in generierten Dokumenten

Was wir im Programm steuern können, ist die Formatierung von Kommentaren, aber diese Art der Formatierung wird von Javadoc nicht erkannt. Wenn Javadoc eine Kommentarzeile findet, entfernt es nur *. und Leerzeichen und übergibt es dann vollständig. Beachten Sie, dass das generierte Dokument vom Typ HTML ist. Solange Sie die HTML-Syntax im Programm kommentieren, können Sie das API-Dokumentformat nicht bearbeiten , weil wir nur eine einfache HTML-Syntax verwenden, z. B. Absatz

, Zeilenumbrüche
Diese reichen aus, schließlich werden die Kommentare nicht sehr lang sein.

@param Parameter 1 Beschreibung (Achten Sie auf das Format)

@Return Rückgabewert Beschreibung (Achten Sie auf das Format)

Wenn es einen Rückgabewert gibt, schreiben Sie ihn. Wenn es keinen Rückgabewert gibt, tun Sie dies nicht Wenn Sie es schreiben, wird ein Fehler gemeldet.

Schreiben Sie einfach /** vor der Klasse oder Methode und drücken Sie dann die Eingabetaste Fügen Sie es automatisch hinzu und die Art und Weise, wie das System es hinzufügt, kann auch von uns geändert werden

So ändern Sie den Inhalt, der beim Erstellen einer neuen Datei angezeigt wird, und wie Sie das automatische Hinzufügen durchführen. Alle Anmerkungen unterliegen unserer Kontrolle (zu erledigen)

Wir sehen dies aus der Standardklassendatei:

Wir alle wissen, dass out ein Attribut (Feld) der Systemklasse ist, die vom Typ PrintStream ist. In der Klasse PrintStream sind viele Methoden definiert, und dies sind natürlich Out-Methoden . Bei der Definition von out gibt es daher viele @see-Anmerkungen davor. Dies ist der beste Ort, um @see-Anmerkungen zu verwenden. Wenn das Feld einen zusammengesetzten Typ hat (. insbesondere ein benutzerdefinierter Verbundtyp), dann kommentieren Sie @see vorne. Dies hat zwei Vorteile, siehe Bild:

Ich glaube, Sie kennen diese beiden Bilder. Das erste ist eine Eingabeaufforderung, die angezeigt wird, wenn der Cursor beim Schreiben eines Programms angezeigt wird. Wenn Sie Kommentare gemäß der Javadoc-Spezifikation schreiben, werden diese auch im Programm angezeigt Du schreibst, das sind sehr hilfreiche Tipps. Die zweite ist die detaillierte Beschreibung des Out-Felds in der String-Klasse im Java8-API-Dokument. Dies ist auch das Verdienst von @see. Sie haben eine solche Anmerkung in Ihrem eigenen Projekt-API-Dokument geschrieben.

Verwandte Empfehlungen: Java-Einführungs-Tutorial

Das obige ist der detaillierte Inhalt vonEinführung in die Javadoc-Spezifikation. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!