如何编写属性的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

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：这个库有很多很酷的功能，你可能想看看

Answer 2

我真的认为这是一个问题，官方Javadoc guide 没有透露任何信息。 C# 可以通过使用 Properties 以一种优雅的方式解决这个问题（我没有用 C# 编写代码，但我真的认为这是一个不错的功能）。

但我有一个猜测：如果你需要解释 someString 是什么，也许它是关于你的代码的“坏小事”。这可能意味着您应该编写 SomeClass 来键入 someString，因此您将在 SomeClass 文档中解释什么是 someString，这样就不需要 getter/setter 中的 javadocs。

Answer 3

在 Eclipse 的自动完成功能的帮助下，我两者都做。

首先，我记录财产：

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

然后，我将其复制并粘贴到 getter：

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

在 Eclipse 中，@return 语句具有自动完成功能 - 因此，我添加单词 Gets，将“t”小写，然后复制带有小写“t”的句子。然后我使用@return（带有 Eclipse 自动完成功能），粘贴句子，然后在 return 中将 T 大写。然后看起来像这样：

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

最后，我将该文档复制到 setter：

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

然后，我对其进行修改，使用 Eclipse 自动完成功能，您不仅可以获得 @param 标记，还可以获得参数名称：

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

然后，我完成了。在我看来，从长远来看，这种模板不仅可以更容易地通过重复提醒自己属性的含义，而且还可以更容易地向 getter 和 setter 添加额外的 cmets，如果你想添加 side效果（例如不允许空属性，将字符串转为大写等）。我为此研究了制作一个 Eclipse 插件，但我找不到适合 JDT 的扩展点，所以我放弃了。

请注意，句子可能并不总是以 T 开头 - 它只是第一个字母必须在粘贴时不大写/重新大写。

Answer 4

您可以在生成 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;
    }
}