如何编写属性的Javadoc？

java javadoc

2022-08-31 10:47:04

我经常发现自己在为“简单”POJO类的属性/成员编写javadoc时遇到两难境地，该类仅包含属性以及getter和setters（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注释。

截至目前，我正在考虑进行练习，只记录 getters，而不是属性。但这似乎不是最好的解决方案...

答案 1

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

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

答案 2

龙目岛是一个非常方便的图书馆，用于此类任务。

@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 方法，并将 javadoc 附加到该字段。@Getter

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