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.

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.

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

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.