No, you haven't specified any JavaDoc comments for the methods. How is someone using or implementing the interface meant to know what the methods are meant to do? You should use proper JavaDoc descriptions:
/**
* This method fromulgates the wibble-wrangler. It should not be called without
* first saturating all glashnashers.
*/
void x();
Bear in mind that unlike most JavaDoc which is aimed at callers, interface documentation has two audiences: callers and implementers. You need to be clear about what both sides can expect and how they should behave. Yes, this is hard to do well :(
EDIT: In terms of the top-level comments:
Personally I'd get rid of the @author tag, as it's rarely useful IMO. (Usually looking in source control is more appropriate...)
Unless you actually have a meaningful versioning policy (not just dates), I'd get rid of the @since tag.
There's no point in stating the source file
A description of "Interface class that has the following methods" is meaningless and contradictory (as an interface isn't a class). Whoever's reading the JavaDoc will already be able to see the list of methods. You should be trying to provide extra information here.
Just like for normal class documentation, interface documentation should state the purpose of the type - its role in the grander scheme of things, perhaps an example of how it's expected to be used, etc. Look at examples in the JDK for generally-reasonable JavaDoc.
Yes you should write proper Javadoc comments for your interfaces to clearly specific the motivation behind the interface and what the contract is for both callers and implementors.
Take a look at some of the interfaces in the JDK code for examples, like java.util.List
发布评论
评论（2）
不，您还没有为这些方法指定任何 JavaDoc 注释。使用或实现接口的人如何知道这些方法的用途？您应该使用正确的 JavaDoc 描述：
请记住，与大多数针对调用者的 JavaDoc 不同，接口文档有两个受众：调用者和实现者。您需要清楚双方可以期望什么以及他们应该如何行事。是的，这很难做好:(
编辑：就顶级评论而言：就
@author标签，因为在我看来它很少有用。（通常查看源代码控制更合适...）@since标签。一样，接口文档应该说明类型的目的 - 它在更宏大的方案中的作用，也许是预期如何使用它的示例，等等。查看示例在 JDK 中一般合理的 JavaDoc。
No, you haven't specified any JavaDoc comments for the methods. How is someone using or implementing the interface meant to know what the methods are meant to do? You should use proper JavaDoc descriptions:
Bear in mind that unlike most JavaDoc which is aimed at callers, interface documentation has two audiences: callers and implementers. You need to be clear about what both sides can expect and how they should behave. Yes, this is hard to do well :(
EDIT: In terms of the top-level comments:
@authortag, as it's rarely useful IMO. (Usually looking in source control is more appropriate...)@sincetag.Just like for normal class documentation, interface documentation should state the purpose of the type - its role in the grander scheme of things, perhaps an example of how it's expected to be used, etc. Look at examples in the JDK for generally-reasonable JavaDoc.
是的，您应该为您的接口编写适当的 Javadoc 注释，以清楚地具体说明接口背后的动机以及调用者和实现者的契约是什么。
查看 JDK 代码中的一些接口作为示例，例如 java.util.List
Yes you should write proper Javadoc comments for your interfaces to clearly specific the motivation behind the interface and what the contract is for both callers and implementors.
Take a look at some of the interfaces in the JDK code for examples, like java.util.List