Java中应该有什么javadoc？

Question

应该通过javadoc注释（类，方法，构造函数和字段？或者只有类方法和构造函数？）来记录什么？ 那有什么约定吗？

请尽可能在答案中提供相关资源的链接。 谢谢

编辑：问题不在于如何通过javadoc进行评论或使用javadoc进行评论是合乎逻辑的。 问题是在任何官方Sun / Oracle文档中可以找到关于此事的内容（关于编写javadoc，约定，规范等的指南）。 另外请不要回答有关javadoc评论应该如何的问题，问题是关于应该评论什么，而不是如何评论。

Answer 1

Javadoc用于记录代码的公共API。

简而言之，您需要记录所有公共和受保护的类，方法，构造函数和字段（因为用户可以访问它们）。

您需要描述方法的作用，而不是它是如何做的。 当然，如果实现细节导致有趣的副作用，例如性能特征以及使用限制，那么应该提及这些副作用。

Oracle有关于“ 如何为Javadoc工具编写Doc注释 ”的官方指南。

Answer 2

Thilo提到的javadoc的简单和一般规则以及此处应该如下：

Javadoc指南

通用规则

• 所有公共和受保护的方法都必须有完整的文档
• 琐碎的getter和setter免于此规则。 干
  什么，但返回或改变一个
  应记录getter或setter中的变量。
• 具有非显而易见的实现的私有方法应该足够了
  允许其他的文档
  开发人员调试它们

官方指南可在此处找到： 如何为Javadoc工具编写Doc注释

Answer 3

想象一下，将代码展示给熟悉编程语言的其他人，而不是您的项目。 无论您认为需要解释哪个部分，因为您正在观看他的评论，应该记录下来。

关于程序员的类似问题.SE： 你应该记录一切还是只记录大部分内容？