使用 JavaDoc 记录 Java 枚举的最佳方法是什么？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/195020/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
What is the best way to use JavaDoc to document a Java enum?
提问by MetroidFan2002
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 用于枚举的最佳方法吗？
采纳答案by Mike Deck
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.
就我个人而言，我对您提供的代码没有任何问题。向我记录枚举似乎是一种完全合理的方式。
回答by anjanb
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”之类的操作来查找内容
回答by Dov Wasserman
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).
正如 Mike 所提到的，你必须用逗号分隔枚举值，并且它们必须是枚举声明中列出的第一件事（实例变量、常量、构造函数和方法可能跟在后面）。
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 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..”）。
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.
如果枚举值描述很短，您可能希望将它们作为 放在一行/** Evaluate first argument first. */，但我建议将每个枚举值保留在自己的行上。大多数 IDE 可以配置为自动以这种方式格式化。
