Come creare Javadoc quando si commenta

December 24

Javadoc è lo standard de facto per generare la documentazione dal codice sorgente. È uno strumento per creare documentazione HTML da commenti appositamente formattati in codice Java. Questo può essere utilizzato per generare automaticamente la documentazione relativa all'interfaccia (API) di programmazione di applicazione strutturata, dare alcuni suggerimenti per l'IDE o per l'attribuzione dei pacchetti, classi e metodi. Essenzialmente, è un modo di commentare le descrizioni del parametro, che ha scritto che cosa e chi dare la colpa se si rompe. Java viene fornito con il programma della riga di comando di javadoc per generare la documentazione HTML, ma la maggior parte degli ambienti di sviluppo Java integrato (IDE) abbiamo anche questo integrato.

Istruzioni

1

Creare commenti javadoc speciale. Per indicare un commento javadoc, iniziare il commento con /. Commenti Javadoc esistono solitamente nella parte superiore di un file, prima di classi e metodi. Poiché è progettato per la documentazione completa di API, non è raro vedere i file con più commenti javadoc rispetto al codice. ""/
This is a javadoc comment. It doesn't have any javadoc meta-tags yet, but it did trigger the javadoc parser to take a look at this comment.
/""

2

Aggiungere API meta-tag (tag che descrivono l'API stessa) quando commentando. Tag di API sono i nomi di parametro, descrizioni, profili di eccezione, le descrizioni di valore restituito, i nomi di metodo e descrizioni del metodo. Molti IDE incorporare questi dati loro descrizioni comandi e altri helper, come pure essendo per l'uso in forma HTML o commento.

3

Utilizzare la descrizione del metodo. Questo meta-tag non ha alcun nome tag: è semplicemente il commento che precede gli altri tag.""/*
Computes the slope of a line.
*/""

4

Incorporare le descrizioni del parametro. Questi sono indicati da @param meta-tag, che dovrebbe essere seguito da un nome di parametro e una descrizione.""/*
Computes the slope of a line.

@param p1 First point that describes the line
@param p2 Second point that describes the line
/""

5

Restituire le descrizioni di valore. Ciò è denotata dal @return meta-tag e dovrebbe essere seguita da una descrizione del valore restituito.""/*
Computes the slope of a line.

@param p1 First point that describes the line
@param p2 Second point that describes the line
@return Slope of the line as a float
*/""

6

Aggiungere tag di attribuzione. Il tag attributo il codice di un autore specifico.""/*
Computes the slope of a line.

@Author Jack Smith
@param p1 First point that describes the line
@param p2 Second point that describes the line
@return Slope of the line as a float
/""

7

Generare la documentazione HTML. Se non utilizzi un IDE o si desidera solo per farlo manualmente, è possibile eseguire il programma da riga di comando di javadoc dalla directory del progetto. Specificare la directory di output con l'opzione -d e passarlo un elenco di file. Java (solitamente come un carattere jolly).""javadoc -d docs *.java""

Consigli & Avvertenze

  • Quando si utilizza un'IDE, documentazione HTML probabilmente è fatto automaticamente come parte del processo di compilazione. Fare riferimento alla documentazione IDE per confermare questo.
  • Commenti su più righe in Java iniziano tradizionalmente con /
  • , ma il carattere asterisco supplementare nel Javadoc segnala il parser di javadoc per iniziare la ricerca di meta-tag di javadoc.

Articoli Correlati