如何编写属性的Javadoc？

在为仅包含属性以及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显示您的吸气剂的javadoc属性描述会很有趣-无需重复javadoc注释。

到目前为止，我正在考虑使我的实践仅记录吸气剂，而不记录属性。但这似乎不是最好的解决方案...

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

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：该库具有许多不错的功能，您可能需要检出

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

首先，我记录该属性：

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

然后，我将其复制并粘贴到吸气剂中：

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

最后，我将该文档复制到设置器中：

/**
 * 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开头-只是粘贴中的第一个字母不能大写/大写。

我真的认为这是一个问题，Javadoc官方指南对此没有任何说明。C＃可以使用Properties用法以优雅的方式解决此问题（我没有用C＃编写代码，但我确实认为这是一个不错的功能）。

但是我有一个猜测：如果您需要解释someString是什么，也许对您的代码来说是一个``坏小事情''。这可能意味着您应该编写SomeClass来键入someString，以便在SomeClass文档中解释什么是someString，而这样就不必使用getter / setter中的javadocs。