Java Language
Documentazione del codice Java
Ricerca…
introduzione
La documentazione per il codice java viene spesso generata usando javadoc . Javadoc è stato creato da Sun Microsystems allo scopo di generare documentazione API in formato HTML dal codice sorgente java. L'utilizzo del formato HTML offre la comodità di essere in grado di collegare insieme documenti correlati.
Sintassi
- / ** - avvio di JavaDoc su una classe, un campo, un metodo o un pacchetto
- @author // Per nominare l'autore della classe, interfaccia o enum. È richiesto.
- @version // La versione di quella classe, interfaccia o enum. È richiesto. È possibile utilizzare macro come% I% o% G% affinché il software di controllo del codice sorgente compili il pagamento.
- @param // Per mostrare gli argomenti (parametri) di un metodo o di un costruttore. Specifica un tag @param per ogni parametro.
- @return // Per mostrare i tipi di ritorno per i metodi non void.
- @exception // Mostra quali eccezioni possono essere generate dal metodo o dal costruttore. Le eccezioni che DEVONO essere catturate dovrebbero essere elencate qui. Se lo desideri, puoi anche includere quelli che non devono essere catturati, come ArrayIndexOutOfBoundsException. Specifica una @ eccezione per ogni eccezione che può essere generata.
- @throws // Uguale a @exception.
- @see // Collegamenti a un metodo, campo, classe o pacchetto. Utilizzare sotto forma di package.Class # qualcosa.
- @since // Quando questo metodo, campo o classe è stato aggiunto. Ad esempio, JDK-8 per una classe come java.util.Optional <T> .
- @serial, @serialField, @serialData // Utilizzato per mostrare serialVersionUID.
- @deprecated // Per contrassegnare una classe, un metodo o un campo come deprecato. Ad esempio, uno sarebbe java.io.StringBufferInputStream . Vedi un elenco completo delle classi deprecate esistenti qui .
- {@link} // Simile a @see, ma può essere utilizzato con testo personalizzato: {@link #setDefaultCloseOperation (int closeOperation) vedi JFrame # setDefaultCloseOperation per maggiori informazioni}.
- {@linkplain} // Simile a {@link}, ma senza il carattere del codice.
- {@code} // per codice letterale, ad esempio tag HTML. Ad esempio: {@code <html> </ html>}. Tuttavia, questo utilizzerà un carattere a spaziatura fissa. Per ottenere lo stesso risultato senza il carattere monospaziale, utilizzare {@literal}.
- {@literal} // Uguale a {@code}, ma senza il carattere a spaziatura fissa.
- {@value} // Mostra il valore di un campo statico: il valore di JFrame # EXIT_ON_CLOSE è {@value}. In alternativa, puoi collegare a un determinato campo: utilizza il nome dell'app {@value AppConstants # APP_NAME}.
- {@docRoot} // La cartella radice del codice HTML JavaDoc relativa al file corrente. Esempio: <a href="{@docRoot}/credits.html"> Crediti </a>.
- L'HTML è permesso: <code> "Ciao cookie" .substring (3) </ code>.
- * / - fine della dichiarazione JavaDoc
Osservazioni
Javadoc è uno strumento incluso con JDK che consente di convertire i commenti nel codice in una documentazione HTML. La specifica dell'API Java è stata generata utilizzando Javadoc. Lo stesso vale per gran parte della documentazione delle librerie di terze parti.
Documentazione di classe
Tutti i commenti Javadoc iniziano con un commento di blocco seguito da un asterisco ( /** ) e terminano quando fa il commento del blocco ( */ ). Facoltativamente, ogni riga può iniziare con spazi bianchi arbitrari e un singolo asterisco; questi vengono ignorati quando vengono generati i file di documentazione.
/**
* Brief summary of this class, ending with a period.
*
* It is common to leave a blank line between the summary and further details.
* The summary (everything before the first period) is used in the class or package
* overview section.
*
* The following inline tags can be used (not an exhaustive list):
* {@link some.other.class.Documentation} for linking to other docs or symbols
* {@link some.other.class.Documentation Some Display Name} the link's appearance can be
* customized by adding a display name after the doc or symbol locator
* {@code code goes here} for formatting as code
* {@literal <>[]()foo} for interpreting literal text without converting to HTML markup
* or other tags.
*
* Optionally, the following tags may be used at the end of class documentation
* (not an exhaustive list):
*
* @author John Doe
* @version 1.0
* @since 5/10/15
* @see some.other.class.Documentation
* @deprecated This class has been replaced by some.other.package.BetterFileReader
*
* You can also have custom tags for displaying additional information.
* Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
* command line option, you can create a custom tag.
*
* Example custom tag and generation:
* @custom.updated 2.0
* Javadoc flag: -tag custom.updated:a:"Updated in version:"
* The above flag will display the value of @custom.updated under "Updated in version:"
*
*/
public class FileReader {
}
Gli stessi tag e formati usati per le Classes possono essere usati anche per Enums e Interfaces .
Documentazione del metodo
Tutti i commenti Javadoc iniziano con un commento di blocco seguito da un asterisco ( /** ) e terminano quando fa il commento del blocco ( */ ). Facoltativamente, ogni riga può iniziare con spazi bianchi arbitrari e un singolo asterisco; questi vengono ignorati quando vengono generati i file di documentazione.
/**
* Brief summary of method, ending with a period.
*
* Further description of method and what it does, including as much detail as is
* appropriate. Inline tags such as
* {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
*
* If a method overrides a superclass method, {@inheritDoc} can be used to copy the
* documentation
* from the superclass method
*
* @param stream Describe this parameter. Include as much detail as is appropriate
* Parameter docs are commonly aligned as here, but this is optional.
* As with other docs, the documentation before the first period is
* used as a summary.
*
* @return Describe the return values. Include as much detail as is appropriate
* Return type docs are commonly aligned as here, but this is optional.
* As with other docs, the documentation before the first period is used as a
* summary.
*
* @throws IOException Describe when and why this exception can be thrown.
* Exception docs are commonly aligned as here, but this is
* optional.
* As with other docs, the documentation before the first period
* is used as a summary.
* Instead of @throws, @exception can also be used.
*
* @since 2.1.0
* @see some.other.class.Documentation
* @deprecated Describe why this method is outdated. A replacement can also be specified.
*/
public String[] read(InputStream stream) throws IOException {
return null;
}
Documentazione sul campo
Tutti i commenti Javadoc iniziano con un commento di blocco seguito da un asterisco ( /** ) e terminano quando fa il commento del blocco ( */ ). Facoltativamente, ogni riga può iniziare con spazi bianchi arbitrari e un singolo asterisco; questi vengono ignorati quando vengono generati i file di documentazione.
/**
* Fields can be documented as well.
*
* As with other javadocs, the documentation before the first period is used as a
* summary, and is usually separated from the rest of the documentation by a blank
* line.
*
* Documentation for fields can use inline tags, such as:
* {@code code here}
* {@literal text here}
* {@link other.docs.Here}
*
* Field documentation can also make use of the following tags:
*
* @since 2.1.0
* @see some.other.class.Documentation
* @deprecated Describe why this field is outdated
*/
public static final String CONSTANT_STRING = "foo";
Documentazione del pacchetto
È possibile creare documentazione a livello di pacchetto in Javadoc utilizzando un file chiamato package-info.java . Questo file deve essere formattato come di seguito. Spazi bianchi iniziali e asterischi facoltativi, tipicamente presenti in ogni riga per motivi di formattazione
/**
* Package documentation goes here; any documentation before the first period will
* be used as a summary.
*
* It is common practice to leave a blank line between the summary and the rest
* of the documentation; use this space to describe the package in as much detail
* as is appropriate.
*
* Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
* and {@literal text here} can be used in this documentation.
*/
package com.example.foo;
// The rest of the file must be empty.
Nel caso precedente, devi inserire questo file package-info.java nella cartella del pacchetto Java com.example.foo .
link
Il collegamento ad altri Javadoc è fatto con il tag @link :
/**
* You can link to the javadoc of an already imported class using {@link ClassName}.
*
* You can also use the fully-qualified name, if the class is not already imported:
* {@link some.other.ClassName}
*
* You can link to members (fields or methods) of a class like so:
* {@link ClassName#someMethod()}
* {@link ClassName#someMethodWithParameters(int, String)}
* {@link ClassName#someField}
* {@link #someMethodInThisClass()} - used to link to members in the current class
*
* You can add a label to a linked javadoc like so:
* {@link ClassName#someMethod() link text}
*/
Con il tag @see puoi aggiungere elementi alla sezione Vedi anche . Come @param o @return il luogo in cui appaiono non è rilevante. Le specifiche dicono che dovresti scriverlo dopo @return .
/**
* This method has a nice explanation but you might found further
* information at the bottom.
*
* @see ClassName#someMethod()
*/
Se si desidera aggiungere collegamenti a risorse esterne, è sufficiente utilizzare il tag HTML <a> . Puoi usarlo in linea ovunque o all'interno di entrambi i tag @link e @see .
/**
* Wondering how this works? You might want
* to check this <a href="http://stackoverflow.com/">great service</a>.
*
* @see <a href="http://stackoverflow.com/">Stack Overflow</a>
*/
Costruire Javadocs dalla riga di comando
Molti IDE forniscono supporto per generare automaticamente HTML da Javadocs; alcuni strumenti di compilazione ( Maven e Gradle , ad esempio) hanno anche plugin in grado di gestire la creazione HTML.
Tuttavia, questi strumenti non sono necessari per generare l'HTML Javadoc; questo può essere fatto usando lo strumento javadoc riga di comando.
L'uso più basilare dello strumento è:
javadoc JavaFile.java
Che genererà HTML dai commenti Javadoc in JavaFile.java .
Un uso più pratico dello strumento della riga di comando, che leggerà in modo ricorsivo tutti i file java in [source-directory] , creerà la documentazione per [package.name] e tutti i sotto-pacchetti, e posizionerà l'HTML generato nella [docs-directory] è:
javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]
Documentazione del codice inline
Oltre al codice di documentazione Javadoc può essere documentato in linea.
I commenti di una singola riga vengono avviati da // e possono essere posizionati dopo un'istruzione sulla stessa riga, ma non prima.
public void method() {
//single line comment
someMethodCall(); //single line comment after statement
}
I commenti su più righe sono definiti tra /* e */ . Possono estendersi su più righe e possono anche essere posizionati tra le dichiarazioni.
public void method(Object object) {
/*
multi
line
comment
*/
object/*inner-line-comment*/.method();
}
I JavaDocs sono una forma speciale di commenti su più righe, a partire da /** .
Poiché troppi commenti in linea possono ridurre la leggibilità del codice, dovrebbero essere usati scarsamente nel caso in cui il codice non sia sufficientemente esplicativo o la decisione di progettazione non sia ovvia.
Un ulteriore caso d'uso per i commenti a riga singola è l'uso di TAG, che sono brevi parole chiave basate sulla convenzione. Alcuni ambienti di sviluppo riconoscono alcune convenzioni per tali commenti singoli. Esempi comuni sono
-
//TODO -
//FIXME
O rilasciare riferimenti, cioè per Jira
-
//PRJ-1234
Frammenti di codice all'interno della documentazione
Il modo canonico di scrivere il codice all'interno della documentazione è con il costrutto {@code } . Se disponi di un code code multiplo all'interno di <pre></pre> .
/**
* The Class TestUtils.
* <p>
* This is an {@code inline("code example")}.
* <p>
* You should wrap it in pre tags when writing multiline code.
* <pre>{@code
* Example example1 = new FirstLineExample();
* example1.butYouCanHaveMoreThanOneLine();
* }</pre>
* <p>
* Thanks for reading.
*/
class TestUtils {
A volte potrebbe essere necessario inserire un codice complesso all'interno del commento javadoc. Il segno @ è particolarmente problematico. L'uso del vecchio tag <code> insieme al {@literal } risolve il problema.
/**
* Usage:
* <pre><code>
* class SomethingTest {
* {@literal @}Rule
* public SingleTestRule singleTestRule = new SingleTestRule("test1");
*
* {@literal @}Test
* public void test1() {
* // only this test will be executed
* }
*
* ...
* }
* </code></pre>
*/
class SingleTestRule implements TestRule { }