Question

假设我正在用Java编写一些复杂的类，我想记录一些关于类的实现的事情（即不应该对该类用户感兴趣的事情，而是希望修改类的实际实现的程序员）。

另外，假设我想写的那些文档说明不是特定于任何单个方法/字段，而是与该类的整个实现相关。这种文档说明的最佳位置在哪里？

在/** … **/块中声明类之前编写注释会使它们成为Javadoc HTML中类的主要描述的一部分，这很糟糕 - 因为我不想打扰它具有该信息的班级用户。

Answer 1

在类声明之前，您始终可以将实现说明编写为非javadoc 注释块/标头，通常是：

package com.example;

import x.y.z.SomeClass;

/* non-javadoc (single asterisk)
Implementation notes:
  - something
  - something else
*/

/** javadoc (double asterisk)
 * Description for consumers of the class
 * @author someone
 */
public class MyClass {
  ...
}

这样，javadoc工具将忽略实现注释注释，并且只会在源文件中显示。

Java中类实现文档说明的正确位置

1 个答案: