如何编写属性的Javadoc？

How to write Javadoc of properties?

提问by

I often find myself with a dilemma when writing javadoc for properties/members of a "simple" POJO class holding only properties and getters and setters (DTO-style)....

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

1) Write javadoc for the property
or...
2) Write javadoc for the getter

1) 为属性编写 javadoc
或...
2) 为 getter 编写 javadoc

If I write javadoc for the property, my IDE (Eclipse) will (naturally) not be able to display this when I later access the POJO via code completion. And there is no standard javadoc tag that lets me link the getter-javadoc to the actual property javadoc.

如果我为该属性编写 javadoc，当我稍后通过代码完成访问 POJO 时，我的 IDE (Eclipse) 将（自然地）无法显示它。并且没有标准的 javadoc 标签可以让我将 getter-javadoc 链接到实际的属性 javadoc。

An example:

一个例子：

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

So, basically it would be interesting to hear how others go about for having your Eclipse IDE display the javadoc property description for your getters - without having to duplicate the javadoc comment.

因此，基本上听听其他人如何让您的 Eclipse IDE 为您的 getter 显示 javadoc 属性描述会很有趣——而不必复制 javadoc 注释。

As of now I'm considering making my practise to only document the getters and not the properties. But it doesn't seem like the best solution...

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

回答by Chandra Sekar

You can include private members while generating Javadocs (using -private) and then use @link to link to that fields property.

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

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

Alternatively, if you do not want to generate the Javadoc for all private members, you can have a convention to document all getters and use @link on setters.

或者，如果您不想为所有私有成员生成 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;
    }
}

回答by MetroidFan2002

I do both, aided by Eclipse's autocomplete.

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

First, I document the property:

首先，我记录财产：

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

Then, I copy and paste this to the getter:

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

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

With eclipse, @return statements have an autocomplete - so, I add the word Gets, lowercase the "t", and copy the sentence with the lowercase "t". I then use @return (with Eclipse autocomplete), paste the sentence, and then uppercase the T in the return. It then looks like this:

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

Finally, I copy that documentation to the setter:

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

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

Then, I modify it and with Eclipse autocomplete you can get not only the @param tag but also the name of the parameter:

然后，我修改它，使用 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;
}

Then, I'm done. In my opinion, this templating makes it a lot easier, in the long run, to not only remind yourself what the property means through repetition, but also it makes it easier to add additional comments to the getter and setter if you want to add side effects (such as not allowing null properties, turning strings to uppercase, etc). I investigated making an Eclipse plugin for this purpose but I couldn't find the appropriate extension point for the JDT, so I gave up.

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

Note that the sentence might not always start with a T - it's just the first letter has to be uncapitalized/recapitalized in pasting.

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

回答by Leonardo Leite

I really think it's a problem and the official Javadoc guidedoes not tell anything about it. C# can solve this in an elegant fashion with the Properties usage (I don't code in C#, but I really think it's a nice feature).

我真的认为这是一个问题，官方Javadoc 指南没有说明任何相关信息。C# 可以通过 Properties 用法以优雅的方式解决这个问题（我不在 C# 中编写代码，但我真的认为这是一个很好的功能）。

But I have a guess: if you need to explain what someString is, maybe it is a ``bad small'' about your code. It can mean that you should write SomeClass to type someString, so you would explain what is someString in the SomeClass documentation, and just so the javadocs in getter/setter would be not necessary.

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

回答by Amanuel Nega

Lombokis a very convenient library for such tasks.

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

That is all you need! The @Getterannotation creates a getter method for each private field and attach the javadoc to it.

这就是你所需要的！该@Getter注释会为每个私人领域的getter方法和javadoc的附加到它。

PS: The library has many cool features you might want to checkout

PS：图书馆有很多很酷的功能，你可能想看看