java - 如何编写属性的Javadoc？

Question

在为仅包含属性和 getter 和 setter(DTO 样式)的“简单”POJO 类的属性/成员编写 javadoc 时，我经常发现自己处于两难境地......

1) 为属性编写javadoc
或者……
2) 为 getter 编写 javadoc

如果我为该属性编写 javadoc，当我稍后通过代码完成访问 POJO 时，我的 IDE (Eclipse) 将(自然)无法显示此内容。并且没有标准的 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 注释。

到目前为止，我正在考虑让我的练习只记录 getter 而不是属性。但这似乎不是最好的解决方案...

Answer 1

您可以在生成 Javadocs(使用 -private)时包含私有(private)成员，然后使用 @link 链接到该字段属性。

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

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

或者，如果您不想为所有私有(private)成员生成 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;
    }
}