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

I've just started using Java's enums in my own projects (I have to use JDK 1.4 at work) and I am confused as to the best practice of using JavaDoc for an enum.

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

I have found that this method works, but the resultant code is a little unrefined:

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

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

Is there any way I could break up the enum declarations on their own lines without chaining them by commas, or is this the best approach for using JavaDoc for an enum?

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

3 个解决方案

#1

To answer the first part of your question, you do have to separate each enum value with a comma. As far as I know, there's no way around that.

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

Personally I don't have a problem with the code the way you've presented it. Seems like a perfectly reasonable way to document an enum to me.

就个人而言，我对代码的呈现方式没有问题。似乎是一个非常合理的方式来记录我的枚举。

#2

As Mike mentioned, you do have to separate the enum values with commas, and they have to be the first things listed in the enum declaration (instance variables, constants, constructors and methods may follow).

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

I think the best way to document enums is similar to regular classes: the enum type gets a description of the function and role of the enum as a whole ("Something values are used to indicate which mode of operation a client wishes...") and each enum value gets a Javadoc description of its purpose and function ("FIRST_THING indicates that the operation should evaluate the first argument first..").

我认为记录枚举的最佳方法类似于常规类：枚举类型获取整个枚举的函数和角色的描述（“Something值用于指示客户希望的操作模式......”并且每个枚举值获得其目的和功能的Javadoc描述（“FIRST_THING表示操作应首先评估第一个参数..”）。

If the enum value descriptions are short you might want to put them on one line as /** Evaluate first argument first. */, but I recommend keeping each enum value on its own line. Most IDEs can be configured to format them this way automatically.

如果枚举值描述很短，您可能希望将它们放在一行上作为/ **首先评估第一个参数。 * /，但我建议将每个枚举值保持在自己的行上。大多数IDE可以配置为自动以这种方式格式化它们。

#3

-2

There is a google code search online tool -- http://www.google.com/codesearch

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

I try to lookup stuff by doing something like "lang:java public enum"

我尝试通过做一些像“lang：java public enum”这样的东西来查找东西

An example from Sun

Sun的一个例子

#1