Introducere în Javadoc

1. Prezentare generală

O bună documentare API este unul dintre mulți factori care contribuie la succesul general al unui proiect software.

Din fericire, toate versiunile moderne ale JDK oferă instrumentul Javadoc - pentru generarea documentației API din comentariile prezente în codul sursă.

Condiții preliminare:

  1. JDK 1.4 (JDK 7+ este recomandat pentru cea mai recentă versiune a pluginului Maven Javadoc)
  2. Dosarul JDK / bin adăugat la variabila de mediu PATH
  3. (Opțional) un IDE cu instrumente încorporate

2. Comentarii Javadoc

Să începem cu comentarii.

Structura comentariilor Javadoc arată foarte asemănătoare cu un comentariu obișnuit pe mai multe linii , dar diferența cheie este asteriscul suplimentar de la început:

// This is a single line comment /* * This is a regular multi-line comment */ /** * This is a Javadoc */

Comentariile stil Javadoc pot conține și etichete HTML.

2.1. Format Javadoc

Comentariile Javadoc pot fi plasate deasupra oricărei clase, metode sau câmpuri pe care dorim să le documentăm.

Aceste comentarii sunt alcătuite în mod obișnuit din două secțiuni:

  1. Descrierea a ceea ce comentăm
  2. Etichetele de blocuri independente (marcate cu simbolul „ @ ”) care descriu meta-date specifice

Vom folosi unele dintre cele mai frecvente etichete de bloc din exemplul nostru. Pentru o listă completă a etichetelor de bloc, vizitați ghidul de referință.

2.2. Javadoc la nivel de clasă

Să aruncăm o privire la cum ar arăta un comentariu Javadoc la nivel de clasă:

/** * Hero is the main entity we'll be using to . . . * * Please see the {@link com.baeldung.javadoc.Person} class for true identity * @author Captain America * */ public class SuperHero extends Person { // fields and methods }

Avem o scurtă descriere și două etichete de bloc diferite - standalone și inline:

  • Etichetele independente apar după descriere, cu eticheta ca primul cuvânt dintr-o linie, de exemplu, eticheta @author
  • Etichetele în linie pot apărea oriunde și sunt înconjurate de paranteze cretate , de exemplu, eticheta @link din descriere

În exemplul nostru, putem vedea, de asemenea, două tipuri de etichete bloc utilizate:

  • {@link} oferă un link inline către o parte a codului sursă la care se face referire
  • @autor numele autorului care a adăugat clasa, metoda sau câmpul comentat

2.3. Javadoc la nivel de câmp

De asemenea, putem folosi o descriere fără etichete de blocare ca aceasta în clasa noastră SuperHero :

/** * The public name of a hero that is common knowledge */ private String heroName;

Câmpuri private nu vor avea Javadoc generat pentru ei dacă nu vom trece în mod explicit privată opțiunea de a comanda Javadoc.

2.4. Javadoc la nivel de metodă

Metodele pot conține o varietate de etichete de bloc Javadoc.

Să aruncăm o privire la o metodă pe care o folosim:

/** * 

This is a simple description of the method. . . * Superman! *

* @param incomingDamage the amount of incoming damage * @return the amount of health hero has after attack * @see HERO-402 * @since 1.0 */ public int successfullyAttacked(int incomingDamage) { // do things return 0; }

SuccessfullyAttacked Metoda conține atât o descriere și numeroase tag - uri bloc autonom.

Există multe etichete de bloc pentru a ajuta la generarea documentației adecvate și putem include tot felul de diferite tipuri de informații. Putem chiar folosi etichete HTML de bază în comentarii.

Să trecem peste etichetele întâlnite în exemplul de mai sus:

  • @param oferă orice descriere utilă despre parametrul sau intrarea unei metode pe care ar trebui să o aștepte
  • @return oferă o descriere a ceea ce o metodă poate sau poate reveni
  • @see va genera un link similar cu eticheta {@link} , dar mai mult în contextul unei referințe și nu în linie
  • @de când specifică ce versiune a fost adăugată la proiect clasa, câmpul sau metoda
  • @version specifică versiunea software-ului, utilizată în mod obișnuit cu macrocomenzile% I% și% G%
  • @throws este folosit pentru a explica în continuare cazurile în care software-ul s-ar aștepta la o excepție
  • @deprecated oferă o explicație a motivului pentru care codul a fost depreciat, când este posibil să fie depreciat și care sunt alternativele

Deși ambele secțiuni sunt opționale din punct de vedere tehnic, vom avea nevoie de cel puțin una pentru instrumentul Javadoc pentru a genera ceva semnificativ.

3. Generația Javadoc

Pentru a genera paginile noastre Javadoc, vom dori să aruncăm o privire asupra instrumentului pentru linia de comandă livrat împreună cu JDK și pluginul Maven.

3.1. Instrument pentru linia de comandă Javadoc

Instrumentul pentru linia de comandă Javadoc este foarte puternic, dar are o anumită complexitate.

Executarea comenzii javadoc fără opțiuni sau parametri va avea ca rezultat o eroare și parametrii de ieșire pe care îi așteaptă.

Va trebui să specificăm cel puțin pentru ce pachet sau clasă dorim să fie generată documentația.

Să deschidem o linie de comandă și să navigăm la directorul proiectului.

Presupunând că clasele sunt toate în folderul src din directorul proiectului:

[email protected]:~$ javadoc -d doc src\*

Aceasta va genera documentație într-un director numit doc așa cum este specificat cu steagul - d . Dacă există mai multe pachete sau fișiere, ar trebui să le furnizăm pe toate.

Utilizarea unui IDE cu funcționalitatea încorporată este, desigur, mai ușoară și în general recomandată.

3.2. Javadoc Cu Maven Plugin

Putem folosi și pluginul Maven Javadoc:

   org.apache.maven.plugins maven-javadoc-plugin 3.0.0  1.8 1.8   ...    

În directorul de bază al proiectului, executăm comanda pentru a genera Javadocs-ul nostru într-un director din target \ site:

[email protected]:~$ mvn javadoc:javadoc

Pluginul Maven este foarte puternic și facilitează generarea complexă de documente fără probleme.

Să vedem acum cum arată o pagină Javadoc generată:

Putem vedea o vedere în arbore a claselor pe care le extinde clasa noastră SuperHero . Putem vedea descrierea, câmpurile și metoda noastră și putem face clic pe linkuri pentru mai multe informații.

O vedere detaliată a metodei noastre arată astfel:

3.3. Etichete Javadoc personalizate

Pe lângă utilizarea etichetelor de bloc predefinite pentru a ne forma documentația, putem crea și etichete de bloc personalizate.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

/** * This is an example... * @location New York * @returns blah blah */

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

Acest tutorial de introducere rapidă a acoperit cum să scrieți Javadocs de bază și să le generați cu linia de comandă Javadoc.

O modalitate mai ușoară de a genera documentația ar fi utilizarea oricăror opțiuni IDE încorporate sau includerea pluginului Maven în fișierul nostru pom.xml și executarea comenzilor corespunzătoare.

Probele de cod, ca întotdeauna, pot fi găsite pe GitHub.