Introduzione a Javadoc

1. Panoramica

Una buona documentazione API è uno dei tanti fattori che contribuiscono al successo complessivo di un progetto software.

Fortunatamente, tutte le versioni moderne di JDK forniscono lo strumento Javadoc, per la generazione della documentazione API dai commenti presenti nel codice sorgente.

Prerequisiti:

  1. JDK 1.4 (JDK 7+ è consigliato per l'ultima versione del plugin Maven Javadoc)
  2. La cartella JDK / bin aggiunta alla variabile d'ambiente PATH
  3. (Opzionale) un IDE con strumenti incorporati

2. Commenti Javadoc

Cominciamo con i commenti.

La struttura dei commenti Javadoc è molto simile a un normale commento su più righe , ma la differenza fondamentale è l'asterisco in più all'inizio:

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

Anche i commenti in stile Javadoc possono contenere tag HTML.

2.1. Formato Javadoc

I commenti Javadoc possono essere posizionati sopra qualsiasi classe, metodo o campo che si desidera documentare.

Questi commenti sono comunemente costituiti da due sezioni:

  1. La descrizione di ciò che stiamo commentando
  2. I tag di blocco indipendenti (contrassegnati con il simbolo " @ ") che descrivono metadati specifici

Useremo alcuni dei tag di blocco più comuni nel nostro esempio. Per un elenco completo dei tag di blocco, visita la guida di riferimento.

2.2. Javadoc a livello di classe

Diamo un'occhiata a come apparirebbe un commento Javadoc a livello di classe:

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

Abbiamo una breve descrizione e due diversi tag di blocco: standalone e inline:

  • I tag autonomi vengono visualizzati dopo la descrizione con il tag come prima parola di una riga, ad esempio il tag @author
  • I tag inline possono apparire ovunque e sono racchiusi tra parentesi graffe , ad esempio, il tag @link nella descrizione

Nel nostro esempio, possiamo anche vedere due tipi di tag di blocco utilizzati:

  • {@link} fornisce un link in linea a una parte di riferimento del nostro codice sorgente
  • @author il nome dell'autore che ha aggiunto la classe, il metodo o il campo commentato

2.3. Javadoc a livello di campo

Possiamo anche usare una descrizione senza tag di blocco come questo all'interno della nostra classe SuperHero :

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

Campi privati non avranno Javadoc generato per loro a meno che non si passa in modo esplicito l' Privata opzione per il comando Javadoc.

2.4. Javadoc a livello di metodo

I metodi possono contenere una varietà di tag di blocco Javadoc.

Diamo un'occhiata a un metodo che stiamo utilizzando:

/** * 

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; }

Il successfullyAttacked metodo contiene sia una descrizione e numerosi tag blocco autonomo.

Ci sono molti tag di blocco per aiutare a generare una corretta documentazione e possiamo includere tutti i tipi di diversi tipi di informazioni. Possiamo anche utilizzare tag HTML di base nei commenti.

Esaminiamo i tag che incontriamo nell'esempio sopra:

  • @param fornisce qualsiasi descrizione utile sul parametro o sull'input di un metodo che dovrebbe aspettarsi
  • @return fornisce una descrizione di ciò che un metodo restituirà o potrà restituire
  • @see genererà un collegamento simile al tag {@link} , ma più nel contesto di un riferimento e non in linea
  • @since specifica quale versione la classe, il campo o il metodo è stato aggiunto al progetto
  • @version specifica la versione del software, comunemente usata con le macro% I% e% G%
  • @throws viene utilizzato per spiegare ulteriormente i casi in cui il software si aspetta un'eccezione
  • @deprecated fornisce una spiegazione del motivo per cui il codice è stato deprecato, quando potrebbe essere stato deprecato e quali sono le alternative

Sebbene entrambe le sezioni siano tecnicamente opzionali, avremo bisogno di almeno una per lo strumento Javadoc per generare qualcosa di significativo.

3. Javadoc Generation

Per generare le nostre pagine Javadoc, vorremo dare un'occhiata allo strumento a riga di comando fornito con JDK e al plugin Maven.

3.1. Strumento della riga di comando Javadoc

Lo strumento della riga di comando Javadoc è molto potente ma presenta una certa complessità.

L'esecuzione del comando javadoc senza alcuna opzione o parametro comporterà un errore e genererà i parametri di output previsti.

Dovremo almeno specificare per quale pacchetto o classe vogliamo che venga generata la documentazione.

Apriamo una riga di comando e andiamo alla directory del progetto.

Supponendo che le classi siano tutte nella cartella src nella directory del progetto:

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

Questo genererà la documentazione in una directory chiamata doc come specificato con il flag - d . Se esistono più pacchetti o file, dovremmo fornirli tutti.

L'utilizzo di un IDE con la funzionalità incorporata è, ovviamente, più facile e generalmente consigliato.

3.2. Javadoc con Maven Plugin

Possiamo anche utilizzare il plugin Maven Javadoc:

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

Nella directory di base del progetto, eseguiamo il comando per generare i nostri Javadoc in una directory in target \ site:

[email protected]:~$ mvn javadoc:javadoc

Il plugin Maven è molto potente e facilita la generazione di documenti complessi senza problemi.

Vediamo ora come appare una pagina Javadoc generata:

Possiamo vedere una visualizzazione ad albero delle classi che la nostra classe SuperHero estende. Possiamo vedere la nostra descrizione, i campi e il metodo e possiamo fare clic sui collegamenti per ulteriori informazioni.

Una vista dettagliata del nostro metodo è simile a questa:

3.3. Tag Javadoc personalizzati

Oltre a utilizzare tag di blocco predefiniti per formattare la nostra documentazione, possiamo anche creare tag di blocco personalizzati.

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

Questo breve tutorial introduttivo ha spiegato come scrivere Javadoc di base e generarli con la riga di comando Javadoc.

Un modo più semplice per generare la documentazione sarebbe utilizzare qualsiasi opzione IDE incorporata o includere il plug-in Maven nel nostro file pom.xml ed eseguire i comandi appropriati.

Gli esempi di codice, come sempre, possono essere trovati su GitHub.