Question

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

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注释。

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

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

我同时使用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自动完成），粘贴句子，然后在返回时将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添加额外的注释效果（例如不允许null属性，将字符串转换为大写等）。我为此目的调查了Eclipse插件，但是我找不到适合JDT的扩展点，所以我放弃了。

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

Answer 3

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 4

我认为这是一个问题而且官方Javadoc guide没有说出任何相关信息。 C＃可以通过“属性”用法以优雅的方式解决这个问题（我不会在C＃中编写代码，但我认为它是一个不错的功能）。

但我有一个猜测：如果你需要解释someString是什么，也许它是一个“糟糕的小”＆＃39;＆＃39;关于你的代码。这可能意味着您应该编写SomeClass来键入someString，因此您可以解释SomeClass文档中的someString，并且只需要getter / setter中的javadocs就不一定了。

如何编写属性的Javadoc？

4 个答案: