Javadoc: documentazione del codice Java

Javadoc è uno strumento fondamentale per ogni sviluppatore Java che vuole produrre una documentazione del codice chiara e di facile consultazione. In questo articolo, analizzeremo come impiegare Javadoc per elevare la qualità della documentazione.

Cos’è Javadoc?

Javadoc è uno strumento di generazione di documentazione incluso nel JDK (Java Development Kit) che estrae i commenti dal codice sorgente Java per creare documentazione HTML. Questo processo non solo facilita la comprensione del codice per altri sviluppatori ma è anche cruciale per mantenere una buona manutenzione del software nel tempo.

screenshot di una sezione della documentazione javdoc per la classe String
Sezione della documentazione Javadoc per le API Java : metodi della classe String

Perché Utilizzare Javadoc?

  • Standardizzazione: Javadoc fornisce un formato standard per documentare le classi Java, i metodi e le variabili.
  • Facilità di Uso: Con pochi semplici commenti, è possibile generare una documentazione completa e strutturata.
  • Integrazione con IDE: La maggior parte degli ambienti di sviluppo integrati (IDE) supporta Javadoc, rendendo la generazione di documentazione un processo fluido e integrato.

Come funziona?

Per utilizzare Javadoc, gli sviluppatori scrivono commenti speciali, noti come commenti Javadoc, direttamente nel codice sorgente. Questi commenti iniziano con /** e terminano con */. All’interno di questi commenti, si possono utilizzare diverse tag Javadoc per descrivere classi, metodi, parametri, eccezioni e altro.

/**
 * Questa classe rappresenta un semplice esempio di utilizzo di Javadoc.
 *
 * @author Nome Autore
 * @version 1.0
 * @since 2024-05-15
 */
public class EsempioJavadoc {
    /**
     * Questo metodo esegue una stampa di prova.
     *
     * @param messaggio Il messaggio da stampare.
     */
    public void stampa(String messaggio) {
        System.out.println(messaggio);
    }
}

Tags per la documentazione

  • @param – Specifica un parametro di un metodo. Utilizzato per descrivere il tipo, il nome e la descrizione del parametro.
  • @return – Descrive il valore di ritorno di un metodo.
  • @exception / @throws – Indica un’eccezione che può essere lanciata dal metodo.
  • @see – Fornisce un riferimento a un’altra parte della documentazione.
  • @since – Indica da quale versione del software è disponibile l’elemento documentato.
  • @version – Specifica la versione del software o del codice.
  • @deprecated – Indica che un elemento è obsoleto e sconsigliato all’uso.
  • @author – Documenta l’autore del codice.
  • @link – Inserisce un collegamento ipertestuale.
  • @code – Permette di includere esempi di codice all’interno dei commenti.
  • @inheritDoc – Eredita la documentazione dalla superclasse o dall’interfaccia implementata.

Generare la documentazione

È importante sapere che non è indispensabile utilizzare gli IDE suggeriti per redigere e produrre la documentazione Javadoc. È possibile impiegare un editor di testo come Visual Studio Code, Sublime Text, Brackets, ecc., e successivamente generare la Javadoc tramite terminale con il comando appropriato.

javadoc -d [directory di destinazione] [nome del pacchetto]

Ad esempio, se vuoi generare la documentazione per il pacchetto com.test e metterla nella directory C:/javadoc/test, il comando sarà:

javadoc -d C:/javadoc/test com.test

Se hai più pacchetti o vuoi specificare un percorso sorgente, puoi aggiungere l’opzione -sourcepath seguita dal percorso della directory contenente i file sorgente.

Ricorda di sostituire [directory di destinazione] e [nome del pacchetto] con i percorsi e i nomi effettivi che intendi utilizzare per la tua documentazione Javadoc.

IntelliJ

Generare la Javadoc in IntelliJ IDEA è un processo semplice. Ecco i passaggi da seguire:

  1. Apri il Progetto: Assicurati di avere il progetto aperto in IntelliJ IDEA.
  2. Vai al Menu ‘Tools’: Nella barra dei menu principale, seleziona ‘Tools’.
  3. Seleziona ‘Generate JavaDoc’: Troverai l’opzione ‘Generate JavaDoc’ nel menu ‘Tools’. Cliccala.
  4. Configura le Opzioni: Nella finestra di dialogo che si apre, potrai selezionare l’ambito per il quale desideri generare la documentazione, come un insieme di file o directory.
  5. Genera la Documentazione: Dopo aver configurato le opzioni, procedi con la generazione della documentazione cliccando su ‘OK’ o ‘Generate’.

Ricorda che puoi anche aggiungere commenti Javadoc automaticamente mentre scrivi il codice. Basta digitare /** sopra la dichiarazione di una classe o metodo e premere ‘Enter’, e IntelliJ completerà automaticamente il commento per te.

screenshot del menu Tools -> Generate JavaDoc del software IntelliJ
Seleziona dal menu Tools la voce Generate JavaDoc...
screenshot del menu JavaDoc Options nel software IntelliJ
Importante: specifica la Output directory ovvero dove verranno generati i file HTML della documentazione JavaDoc.

Eclipse

 Ecco i passaggi da seguire:

  1. Apri Eclipse: Avvia l’IDE Eclipse e apri il progetto per il quale desideri generare la Javadoc.
  2. Seleziona ‘Project’ dal Menu: Nella barra dei menu, clicca su ‘Project’.
  3. Scegli ‘Generate Javadoc’: Troverai l’opzione ‘Generate Javadoc…’ nel menu ‘Project’. Selezionala.
  4. Configura il Wizard di Generazione: Nella finestra di dialogo che appare, dovrai:
    • Specificare la posizione del programma javadoc sul tuo computer (di solito si trova nella directory bin di JAVA_HOME).
    • Selezionare il progetto e i pacchetti per cui vuoi generare la Javadoc.
    • Limitare i file sorgente per cui verranno generate le Javadoc (tutti i file sono selezionati per impostazione predefinita).
    • Limitare quali membri della classe avranno le Javadoc generate, scegliendo la visibilità (modificatore di accesso).
    • Specificare la directory di destinazione dove verranno messe le Javadoc.
  5. Imposta Argomenti e Opzioni: Nella schermata successiva, potrai specificare alcuni argomenti e opzioni per lo strumento javadoc, come il titolo del documento e la struttura del documento.
  6. Completa la Generazione: Infine, dopo aver configurato tutte le opzioni, clicca su ‘Finish’ per generare la documentazione
Screenshot del menu Project voce Generate Javadoc.. nel software Eclipse
Seleziona dal menu Project la voce Generate Javadoc...

Esempio codice

/**
 * The class Calculator contains methods for performing arithmetic operations.
 * The implemented methods allow you to perform:
 * <ul>
 *     <li>Addition</li>
 *     <li>Difference</li>
 *     <li>Multiplication</li>
 *     <li>Division</li>
 * </ul>
 * @author Carlo Contardi
 * @since 1.0.0
 */
public class Calculator {

    public Calculator(){

    }

    /**
     * This method returns the sum of two integers
     * @param a
     * @param b
     * @return Returns the sum of two int values
     */
    public int add(int a, int b){
        return a+b;
    }
    /**
     * This method returns the sum of two doubles
     * @param a
     * @param b
     * @return Returns the sum of two double values
     */
    public double add(double a, double b){
        return a+b;
    }
}

Risorse utili

Scrivi codice pulito in Java : Clean Code in Java – SpaceCoding

Conclusione

Javadoc è più di un semplice strumento di documentazione; è una convenzione che promuove la chiarezza e la collaborazione tra sviluppatori. Utilizzando Javadoc in modo efficace, puoi assicurarti che il tuo codice Java sia accessibile e comprensibile per tutti coloro che vi lavorano, oggi e in futuro.

Pubblicato da Carlo Contardi

Carlo Contardi, docente di informatica e sviluppatore Full Stack, condivide la sua passione per la programmazione e l’informatica attraverso il suo blog Space Coding. Offre preziosi consigli e soluzioni pratiche a chi vuole imparare a programmare o migliorare le proprie abilità. 🚀👨‍💻

Translate »