Java中类实现文档说明的正确位置[关闭]答案

【问题标题】：The correct place for class-implementation documentation notes in Java [closed]Java中类实现文档说明的正确位置[关闭]
【发布时间】：2016-03-12 12:57:33
【问题描述】：

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

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

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

【问题讨论】：

标签： java documentation javadoc code-documentation

【解决方案1】：

您始终可以在类声明之前将实现注释写为 non-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工具会忽略实现注释注释，只在源文件中可见。

【讨论】：