Come scrivere Javadoc di proprietà?

Spesso mi trovo di fronte a un dilemma quando scrivo javadoc per proprietà / membri di una classe POJO "semplice" che contiene solo proprietà e getter e setter (stile DTO) ....

1) Scrivi javadoc per la proprietà
o ...
2) Scrivi javadoc per il getter

Se scrivo javadoc per la proprietà, il mio IDE (Eclipse) non sarà (naturalmente) in grado di visualizzarlo quando accederò successivamente al POJO tramite il completamento del codice. E non esiste un tag javadoc standard che mi consenta di collegare il getter-javadoc alla proprietà javadoc effettiva.

Un esempio:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }  

Quindi, fondamentalmente sarebbe interessante sentire come fanno gli altri per avere il tuo IDE Eclipse per visualizzare la descrizione della proprietà javadoc per i tuoi getter, senza dover duplicare il commento javadoc.

Per ora sto considerando di fare pratica per documentare solo i getter e non le proprietà. Ma non sembra la soluzione migliore ...

È possibile includere membri privati ​​durante la generazione di Javadoc (utilizzando -private) e quindi utilizzare @link per collegarsi a quella proprietà dei campi.

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

In alternativa, se non vuoi generare Javadoc per tutti i membri privati, puoi avere una convenzione per documentare tutti i getter e utilizzare @link sui setter.

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}

Lombok è una libreria molto conveniente per tali attività.

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

È tutto ciò di cui hai bisogno! L' @Getterannotazione crea un metodo getter per ogni campo privato e vi allega il javadoc.

PS : La libreria ha molte funzioni interessanti che potresti voler controllare

Faccio entrambe le cose, aiutato dal completamento automatico di Eclipse.

Per prima cosa, documento la proprietà:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Quindi, copio e incollo questo nel getter:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Con eclipse, le istruzioni @return hanno un completamento automatico, quindi aggiungo la parola Gets, minuscolo la "t" e copio la frase con la "t" minuscola. Quindi uso @return (con il completamento automatico di Eclipse), incollo la frase e poi la T maiuscola nel ritorno. Quindi assomiglia a questo:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Infine, copio quella documentazione sul setter:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Quindi, lo modifico e con il completamento automatico di Eclipse puoi ottenere non solo il tag @param ma anche il nome del parametro:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Allora ho finito. A mio parere, questo modello rende molto più semplice, a lungo termine, non solo ricordare a te stesso cosa significa la proprietà attraverso la ripetizione, ma rende anche più facile aggiungere commenti aggiuntivi al getter e al setter se vuoi aggiungere lato effetti (come non consentire proprietà nulle, trasformare le stringhe in maiuscolo, ecc.). Ho cercato di creare un plug-in Eclipse per questo scopo, ma non sono riuscito a trovare il punto di estensione appropriato per JDT, quindi ho rinunciato.

Nota che la frase potrebbe non iniziare sempre con una T: è solo che la prima lettera deve essere senza maiuscole / ricapitalizzata per incollare.

Penso davvero che sia un problema e la guida ufficiale di Javadoc non dice nulla al riguardo. C # può risolvere questo problema in modo elegante con l'utilizzo delle proprietà (non codifico in C #, ma penso davvero che sia una bella funzionalità).

Ma ho una supposizione: se hai bisogno di spiegare cos'è someString, forse è un `` cattivo piccolo '' sul tuo codice. Può significare che dovresti scrivere SomeClass per digitare someString, quindi spiegheresti cos'è someString nella documentazione SomeClass, e solo così i javadoc in getter / setter non sarebbero necessari.