使用 JavaDoc 记录 Java 枚举的最佳方法是什么？答案

【问题标题】：What is the best way to use JavaDoc to document a Java enum?使用 JavaDoc 记录 Java 枚举的最佳方法是什么？
【发布时间】：2008-10-12 02:46:54
【问题描述】：

我刚刚开始在我自己的项目中使用 Java 的枚举（我必须在工作中使用 JDK 1.4），我对使用 JavaDoc 进行枚举的最佳实践感到困惑。

我发现这个方法可行，但是生成的代码有点不完善：

/**
* Doc for enum
*/
public enum Something {
/**
* First thing
*/
FIRST_THING,
/**
* Second thing
*/
SECOND_THING;
//could continue with more
}

有没有什么方法可以在不使用逗号链接的情况下将枚举声明拆分到它们自己的行中，或者这是将 JavaDoc 用于枚举的最佳方法？

【问题讨论】：

其实至少对于JDK1.7（其他版本未测试），在每个枚举值后面加逗号是完全合法的，包括最后一个。只需在最后一个值后的行上加一个分号，就可以了。这样可以更轻松地移动值或添加/删除值，而不必担心使用逗号或分号。

标签： java enums javadoc

【解决方案1】：

要回答问题的第一部分，您必须用逗号分隔每个枚举值。据我所知，没有办法解决。

就我个人而言，您提供的代码没有问题。似乎是向我记录枚举的一种完全合理的方式。

【讨论】：

【解决方案2】：

正如 Mike 所提到的，你必须用逗号分隔枚举值，并且它们必须是枚举声明中列出的第一件事（实例变量、常量、构造函数和方法可能紧随其后）。

我认为记录枚举的最佳方式类似于常规类：枚举类型获取对整个枚举的功能和角色的描述（“Something values are used to indicate which mode of operation a client wishes...”），每个枚举值获取一个 Javadoc 描述它的目的和功能（“FIRST_THING indicates that the operation should evaluate the first argument first..”）。

如果枚举值描述很短，您可能希望将它们作为/** Evaluate first argument first. */ 放在一行中，但我建议将每个枚举值保留在自己的行中。大多数 IDE 都可以配置为自动以这种方式格式化它们。

【讨论】：

【解决方案3】：

有一个google代码搜索在线工具--http://www.google.com/codesearch

我尝试通过 "lang:java public enum" 之类的方式查找内容

An example from Sun

【讨论】：