Javadoc è uno strumento sviluppato da Oracle , per creare una documentazione di API in formato HTML dai commenti presenti in un codice sorgente in Java .
Progettato originariamente da Sun MicroSystems (prima della sua acquisizione da parte di Oracle), javadoc è lo standard industriale per la documentazione delle classi Java. La maggior parte degli IDE genera automaticamente javadoc in formato HTML .
Quando commentano il codice sorgente, gli sviluppatori Java possono segnalare che un commento deve essere incorporato nella documentazione utilizzando una sintassi speciale. Un blocco di commenti Java che inizia con /**diventerà un blocco di commenti Javadoc che sarà incluso nella documentazione del codice sorgente. I commenti Javadoc di solito precedono le dichiarazioni di classi, attributi e metodi. È anche possibile descrivere un pacchetto, creando un file package-info.javanella cartella corrispondente, in cui includiamo un commento Javadoc.
Un tag Javadoc inizia con un @( at ). La tabella seguente mostra alcuni dei tag più comuni:
Etichetta | Descrizione |
---|---|
@author | Nome dello sviluppatore |
@deprecated | Contrassegna il metodo come obsoleto . Alcuni IDE creano un avviso di compilazione se il metodo viene chiamato. |
@exception | Documenta un'eccezione lanciata da un metodo - vedi anche @throws. |
@param | Definisce un parametro del metodo. Obbligatorio per ogni impostazione. |
@return | Documenta il valore restituito . Questo tag non deve essere utilizzato per costruttori o metodi definiti con un tipo restituito void . |
@see | Documenta un'associazione a un altro metodo o classe. |
@since | Specifica in cui la versione del SDK / JDK un metodo è stato aggiunto alla classe. |
@throws | Documenta un'eccezione generata da un metodo. Un sinonimo di @exceptiondisponibile da Javadoc 1.2. |
@version | Fornisce la versione di una classe o di un metodo. |
Un esempio di utilizzo di Javadoc per documentare un metodo:
/** * Valide un mouvement de jeu d'Echecs. * @param leDepuisFile File de la pièce à déplacer * @param leDepuisRangée Rangée de la pièce à déplacer * @param leVersFile File de la case de destination * @param leVersRangée Rangée de la case de destination * @return vrai (true) si le mouvement d'échec est valide ou faux (false) sinon */ boolean estUnDeplacementValide(int leDepuisFile, int leDepuisRangée, int leVersFile, int leVersRangée) { ... }Un esempio di utilizzo di Javadoc per documentare una classe:
/** * Classe de gestion d'étudiants * @author John Doe * @version 2.6 */ public class Etudiant { ... }Javadoc fornisce anche un'API per la creazione di doclet e taglet , che consentono di analizzare la struttura di un'applicazione Java. È grazie a questo che JDiff può produrre report di ciò che è cambiato tra due versioni di un'API .
Tuttavia, il concetto consente solo di produrre il documento API in una lingua.