Özelliklerin Javadoc'u nasıl yazılır?

Sadece özellikleri ve alıcıları ve ayarlayıcıları (DTO tarzı) tutan "basit" bir POJO sınıfının özellikleri / üyeleri için javadoc yazarken sık sık kendimi bir ikilemle buluyorum ...

1) Mülk için javadoc yazın
veya ...
2) Alıcı için javadoc yazın

Özellik için javadoc yazarsam, IDE'm (Eclipse) daha sonra kod tamamlama yoluyla POJO'ya eriştiğimde (doğal olarak) bunu görüntüleyemeyecek. Ve getter-javadoc'u gerçek javadoc özelliğine bağlamamı sağlayan standart bir javadoc etiketi yok.

Bir örnek:

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

Bu nedenle, temelde başkalarının Eclipse IDE'nizin alıcılarınız için javadoc özellik açıklamasını javadoc yorumunu çoğaltmak zorunda kalmadan görüntülemesi için nasıl davrandığını duymak ilginç olurdu.

Şu an itibariyle muayenehanemi mülkleri değil, yalnızca alıcıları belgelemek için yapmayı düşünüyorum. Ama en iyi çözüm gibi görünmüyor ...

Javadocs oluştururken (-özel kullanarak) özel üyeler ekleyebilir ve ardından bu alanlar özelliğine bağlanmak için @link kullanabilirsiniz.

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

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

Alternatif olarak, tüm özel üyeler için Javadoc oluşturmak istemiyorsanız, tüm alıcıları belgelemek ve ayarlayıcılarda @link kullanmak için bir kurala sahip olabilirsiniz.

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 , bu tür görevler için çok uygun bir kütüphanedir.

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

Tek ihtiyacın olan bu! @GetterEk açıklama her özel alan için bir alıcı yöntemini oluşturur ve buna javadoc ekleyin.

Not : Kitaplık, kontrol etmek isteyebileceğiniz birçok harika özelliğe sahiptir

Eclipse'in otomatik tamamlamasının yardımıyla ikisini de yapıyorum.

İlk olarak, özelliği belgeliyorum:

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

Sonra bunu alıcıya kopyalayıp yapıştırıyorum:

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

Eclipse ile, @return deyimlerinin bir otomatik tamamlama özelliği vardır - bu nedenle, Gets sözcüğünü ekliyorum, "t" harfini küçük harfle yazıyorum ve cümleyi küçük "t" harfiyle kopyalıyorum. Daha sonra @return kullanıyorum (Eclipse otomatik tamamlama ile), cümleyi yapıştırıyorum ve dönüşte T harfini büyük harflerle yazıyorum. Daha sonra şuna benzer:

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

Son olarak, bu dokümantasyonu ayarlayıcıya kopyalıyorum:

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

Ardından, onu değiştiriyorum ve Eclipse otomatik tamamlama ile yalnızca @param etiketini değil, aynı zamanda parametrenin adını da alabiliyorsunuz:

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

Sonra bitirdim. Kanımca, bu şablon, uzun vadede, yalnızca mülkün tekrarlama yoluyla kendinize ne anlama geldiğini hatırlatmayı çok daha kolaylaştırmakla kalmaz, aynı zamanda taraf eklemek istiyorsanız alıcıya ve ayarlayıcıya ek yorumlar eklemeyi de kolaylaştırır. efektler (boş özelliklere izin vermeme, dizeleri büyük harfe çevirme vb.). Bu amaçla Eclipse eklentisi yapmayı araştırdım ancak JDT için uygun uzantı noktasını bulamadığım için pes ettim.

Cümlenin her zaman bir T ile başlamayabileceğini unutmayın - sadece ilk harfin büyük harfsiz / yapıştırmada yeniden büyük harfle yazılmış olması gerekir.

Bunun bir sorun olduğunu düşünüyorum ve resmi Javadoc rehberi bu konuda hiçbir şey söylemiyor. C # bunu Özellikler kullanımıyla zarif bir şekilde çözebilir (C # ile kodlamam, ancak bunun gerçekten güzel bir özellik olduğunu düşünüyorum).

Ama bir tahminim var: someString'in ne olduğunu açıklamanız gerekiyorsa, belki kodunuz hakkında `` kötü bir küçük '' olabilir. Bu, someString yazmak için SomeClass yazmanız gerektiği anlamına gelebilir, bu nedenle SomeClass belgelerinde someString'in ne olduğunu açıklarsınız ve getter / setter'daki javadocs'un gerekli olmaması için.