class-实现文档注释的正确位置在Java

Question

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

另外，假设我想写的那些文档说明 不特定于任何一个 method/field，而是与 class 的整个实现相关.此类文档注释的最佳位置在哪里？

在 /** … **/ 块中的 class 声明之前写注释将使它们成为 Java 文档中 class 的主要描述的一部分HTML，这很糟糕 - 因为我不想用这些信息打扰 class 的用户。

Answer 1

您始终可以在 class 声明之前将实施说明写为 non-javadoc 注释块/header，通常：

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 工具忽略，只会在源文件中可见。

class-实现文档注释的正确位置在Java

The correct place for class-implementation documentation notes in Java

java

documentation

javadoc

code-documentation