Java中应该有什么javadoc？

Question

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

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

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

Answer 1

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

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

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

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