使用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可以配置为自动以这种方式格式化它们.