Bagaimana cara menulis properti Javadoc?

Saya sering menemukan diri saya dengan dilema ketika menulis javadoc untuk properti / anggota kelas POJO "sederhana" yang hanya memiliki properti dan pengambil serta penyetel (gaya DTO) ....

1) Tulis javadoc untuk properti
atau ...
2) Tulis javadoc untuk pengambil

Jika saya menulis javadoc untuk properti tersebut, IDE (Eclipse) saya (secara alami) tidak akan dapat menampilkan ini ketika saya mengakses POJO nanti melalui penyelesaian kode. Dan tidak ada tag javadoc standar yang memungkinkan saya menghubungkan getter-javadoc ke properti javadoc yang sebenarnya.

Sebuah contoh:

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;  
  }  

Jadi, pada dasarnya akan menarik untuk mendengar bagaimana orang lain meminta Eclipse IDE Anda menampilkan deskripsi properti javadoc untuk getter Anda - tanpa harus menduplikasi komentar javadoc.

Sampai sekarang saya sedang mempertimbangkan untuk membuat latihan saya hanya untuk mendokumentasikan getter dan bukan properti. Tapi sepertinya itu bukan solusi terbaik ...

Anda dapat menyertakan anggota pribadi saat membuat Javadocs (menggunakan -private) dan kemudian menggunakan @link untuk menautkan ke properti bidang tersebut.

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

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

Alternatifnya, jika Anda tidak ingin membuat Javadoc untuk semua anggota privat, Anda bisa memiliki konvensi untuk mendokumentasikan semua getter dan menggunakan @link pada 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 adalah perpustakaan yang sangat nyaman untuk tugas-tugas semacam itu.

@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;
}

Hanya itu yang Anda butuhkan! The @Getterpenjelasan menciptakan metode pengambil untuk setiap bidang swasta dan melampirkan javadoc untuk itu.

NB : Perpustakaan memiliki banyak fitur keren yang mungkin ingin Anda periksa

Saya melakukan keduanya, dibantu oleh pelengkapan otomatis Eclipse.

Pertama, saya mendokumentasikan properti:

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

Lalu, saya salin dan tempel ini ke getter:

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

Dengan eclipse, pernyataan @return memiliki pelengkapan otomatis - jadi, saya menambahkan kata Gets, huruf kecil "t", dan salin kalimat dengan huruf kecil "t". Saya kemudian menggunakan @return (dengan pelengkapan otomatis Eclipse), menempelkan kalimat, dan kemudian menggunakan huruf besar T sebagai balasannya. Kemudian terlihat seperti ini:

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

Akhirnya, saya menyalin dokumentasi itu ke penyetel:

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

Kemudian, saya memodifikasinya dan dengan pelengkapan otomatis Eclipse Anda tidak hanya bisa mendapatkan tag @param tetapi juga nama parameternya:

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

Kemudian, saya selesai. Menurut pendapat saya, template ini membuatnya jauh lebih mudah, dalam jangka panjang, untuk tidak hanya mengingatkan diri Anda sendiri apa arti properti melalui pengulangan, tetapi juga memudahkan untuk menambahkan komentar tambahan ke getter dan setter jika Anda ingin menambahkan sisi. efek (seperti tidak mengizinkan properti null, mengubah string menjadi huruf besar, dll). Saya menyelidiki pembuatan plugin Eclipse untuk tujuan ini tetapi saya tidak dapat menemukan titik ekstensi yang sesuai untuk JDT, jadi saya menyerah.

Perhatikan bahwa kalimat mungkin tidak selalu dimulai dengan T - hanya saja huruf pertama harus tidak dikapitalisasi / direkapitalisasi dalam penempelan.

Saya benar-benar berpikir itu adalah masalah dan panduan resmi Javadoc tidak menceritakan apapun tentang itu. C # dapat menyelesaikan ini dengan cara yang elegan dengan penggunaan Properties (Saya tidak membuat kode dalam C #, tapi menurut saya ini fitur yang bagus).

Tapi saya punya tebakan: jika Anda perlu menjelaskan apa itu someString, mungkin itu adalah `` kecil yang buruk '' tentang kode Anda. Ini bisa berarti bahwa Anda harus menulis SomeClass untuk mengetik someString, jadi Anda akan menjelaskan apa itu someString dalam dokumentasi SomeClass, dan agar javadocs di getter / setter tidak diperlukan.