如何编写属性的Javadoc？

Question

当我为一个"简单"POJO类的属性/成员编写javadoc时,我常常发现自己处于两难境地,只持有属性和getter和setter(DTO风格)....

1)为属性写javadoc
或...
2)为getter写javadoc

如果我为属性编写javadoc,我的IDE(Eclipse)将(当然)在以后通过代码完成访问POJO时无法显示.并且没有标准的javadoc标记允许我将getter-javadoc链接到实际的属性javadoc.

一个例子:

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

所以,基本上有趣的是听到其他人如何让你的Eclipse IDE显示你的getter的javadoc属性描述 - 而不必复制javadoc注释.

截至目前,我正在考虑让我的练习只记录吸气剂而不是属性.但它似乎不是最好的解决方案......

Answer 1

您可以在生成Javadocs时使用私有成员(使用-private),然后使用@link链接到该fields属性.

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

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

或者,如果您不想为所有私有成员生成Javadoc,则可以使用约定来记录所有getter并在setter上使用@link.

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

Answer 2

Lombok是执行此类任务的非常方便的库。

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

这就是您所需要的！该@Getter注释为每个私有字段创建一个 getter 方法并将 javadoc 附加到它。

PS：该库有许多很酷的功能，您可能想看看