如何编写属性的Javadoc？

在为只包含属性和getter、setter（DTO样式）的“简单”POJO类的属性/成员编写javadoc时，我经常会发现自己陷入两难境地

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

如果我为该属性编写javadoc，那么当我稍后通过代码完成访问POJO时，我的IDE（Eclipse）将（自然）无法显示该属性。没有标准的javadoc标记允许我将getterjavadoc链接到实际的属性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;  
  }  

因此，听到其他人如何让EclipseIDE为getter显示javadoc属性描述，而不必重复javadoc注释，基本上是很有趣的

---

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

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

---

在Eclipse的自动完成的帮助下，我做到了这两件事

首先，我记录了该属性：

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

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

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

在eclipse中，@return语句具有自动完成功能，因此，我添加单词get，小写字母“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 autocomplete，您不仅可以获得@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添加附加注释。为此，我研究了制作一个Eclipse插件，但是我找不到适合JDT的扩展点，所以我放弃了

---

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

我真的认为这是一个问题，官员没有透露任何信息。C#可以通过使用属性以优雅的方式解决这个问题（我不使用C#编写代码，但我真的认为这是一个很好的特性）

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

对于此类任务来说是一个非常方便的库

@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/javadoc的问题。看起来他们的结论是我在考虑的。。。只在getters中编写属性javadoc。我找到了一种方法，可以在eclipse中工作，甚至可以在运行时收集注释，这是一个选项吗？私有成员需要javadoc？bla bla bla的名称：best exampleCopy/paste is evil。。。而且很费时。这些步骤看起来需要做很多工作，如果javadoc发生更改，您将有3个不同的地方需要更新。我认为插件也不能证明这一点。。。至少，插件必须考虑到属性javADoc是主，然后覆盖GETSter（和SETTER）。我想要完成的是在一个地方编写javadoc，然后让getter和属性javadoc采用相同的描述……通常，属性不会经常更改。而复制和粘贴操作，使用Eclipse的autocomplete，在构建属性Javadoc后只需不到30秒的时间。。。引入这种复制/粘贴方案必然会导致不一致。我对其他厨师（或我自己）以后编辑代码的信心太小了。另外，至少如果您没有一个完整的前期设计，javadoc属性经常会发生变化，至少在实验/设计阶段是如此。而javadoc如果是在代码还没被记起的时候编写的，质量会更好。。。抱歉，如果我看起来像个爱发牢骚的人；-）抱歉，但是编辑属性必然会导致不一致性——无论您使用哪种方式，Javadoc都会被搁置一旁，除非以某种方式对其进行大力维护。即使有一种简单的方法可以公开属性javadoc，也很可能不会更新属性javadoc本身。这实际上是团队的编码约定等问题，还有代码审查之类的事情——祝你好运，这就是我的方式，所以我不会忘记。@Metroid——除非以某种方式大力维护它——如果它被视为源代码本身的一部分，那么应该大力维护它。而且不把Javadoc注释（以及其他语言中的等价物）作为代码的固有部分，尽管这是一种标准做法，但却是许多罪恶的根源。最糟糕的评论是已经过时的评论。充其量，它们会让程序员无法掌握代码（因为他们必须不断地重新验证和接受/拒绝过时的注释）。更糟糕的是，它们会提供容易出错、引入错误的信息。我用@link和@see标记进行了试验。。但是至少Eclipse没有显示这个p