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

Question

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

我发现这个方法有效，但结果代码有点未定义：

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

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

Answer 1

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

我个人认为代码没有问题。似乎是一种向我记录枚举的完美合理的方式。

Answer 2

正如迈克所提到的，你必须用逗号分隔枚举值，它们必须是枚举声明中列出的第一个东西（实例变量，常量，构造函数和方法可能会跟随）。

我认为记录枚举的最佳方法与常规类相似：枚举类型获取整个枚举的函数和作用的描述（“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都可以配置为自动格式化它们。

Answer 3

谷歌代码搜索在线工具 - http://www.google.com/codesearch

我尝试通过执行"lang:java public enum"

之类的操作来查找内容

An example from Sun