如何编写属性的 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 显示 getter 的 javadoc 属性描述的，而不必复制 javadoc 注释的，这将是一件有趣的事情。

到目前为止，我正在考虑使我的实践只记录 getter，而不是属性。但这似乎不是最好的解决办法。

107535 次浏览
小开

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

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.

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

I do both, aided by Eclipse's autocomplete.

First, I document the property:

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

Then, I copy and paste this to the 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:

/**
* 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:

/**
* 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:

/**
* 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.

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

小开

I really think it's a problem and the official Javadoc guide does 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).

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.

小开

Lombok is a very convenient library for such tasks. 

@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 @Getter annotation creates a getter method for each private field and attach the javadoc to it.

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


提交答案