如何最好地使用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枚举，这是最好的方法吗？

- MetroidFan2002

---

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

Answer 1

回答您问题的第一部分，您确实需要使用逗号将每个枚举值分隔开。据我所知，没有其他方法。

就个人而言，我对您呈现的代码没有任何问题。在我看来，这似乎是记录枚举的一个完全合理的方式。

- Mike Deck

Answer 2

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

我认为记录枚举的最佳方式类似于普通类：枚举类型会获得关于整个枚举功能和作用的描述（“某些值用于指示客户端希望的操作模式...”），每个枚举值都会获得一个Javadoc描述其目的和功能的描述（“FIRST_THING表示该操作应首先评估第一个参数..”）。

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

- Dov Wasserman

Answer 3

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

我尝试通过这样的方式查找一些东西 "lang:java public enum"

来自 Sun 的一个例子

- anjanb