如何 Javadoc 类的单个枚举答案

【问题标题】：How to Javadoc a Class's Individual Enums如何 Javadoc 类的单个枚举
【发布时间】：2011-09-26 20:21:35
【问题描述】：

我正在为一个包含自己的枚举的类编写 Javadoc。有没有办法为各个枚举生成 Javadoc？例如，现在我有这样的东西：

/**
 * This documents "HairColor"
 */
private static enum HairColor { BLACK, BLONDE, BROWN, OTHER, RED };

但是，这只是将所有枚举作为一个整体进行记录：

有没有办法单独记录每个HairColor 值？不将枚举移动到自己的类中或从枚举中更改它？

【问题讨论】：

出于好奇，你为什么要这样做？您将枚举列为private 嵌套枚举，因此您的类的用户无论如何都不能使用枚举或其值。如果它是公开的和独立的，那么将它作为一个独立的单元记录有什么大不了的？
在我的实际代码中，它是公开的。而且您知道公司标准如何。 “这样会更好” “太糟糕了，我们这些对编程一无所知的人认为你应该这样做”。大声笑
很公平。只要确保你告诉他们发布将被推迟一周，因为对可能永远不会阅读的文档的不可动摇的要求。这通常会引起那些关心业务的人的耳朵。
哈哈。 Javadoc 作为 javadoc 是相当不被使用的。但我喜欢它的编码。一些程序员的方法名称与实际发生的事情无关。就像 getCat 返回过去 10 天里所有跑过树的猫，不包括周二或节假日。哈哈
@RachelG。每个开发者都认为她/他优于其他开发者，这是一个相当普遍的现象。不过没有冒犯。

标签： java enums javadoc

【解决方案1】：

您可以像使用 javadoc 的任何其他变量一样执行此操作。


/**
 *  Colors that can be used
 */
public enum Color
{
    /**
     * Red color
     */
    red,

    /**
     * Blue color
     */
    blue

}

编辑：

来自 Paŭlo Ebermann：枚举是一个单独的类。您不能在封闭类中包含其完整文档（至少，在不修补标准 doclet 的情况下）。

【讨论】：

这会生成相同的东西（注意快照上的链接）。我希望将它们直接放在类 javadoc 中（而不是链接到另一个 javadoc）。但是感谢 =) +1 推进问题描述。
@Rachel：枚举是一个单独的类。您不能在封闭类中包含其完整文档（至少，在不修补标准 doclet 的情况下）。
是的。我有点担心链接发生时的情况。我想包含单个枚举的唯一方法是将其更改为内部类，然后在其中声明对象并对其进行 javadoc。
@user489041：您能否将重要的 cmets（例如我的）合并到答案中，以供将来参考？
如果你想引用它，你总是可以使用{@link Color}甚至{@link Color#red}，或者甚至只是{@link #red}在任何其他javadoc中的同一个文档中，包括类javadoc.

【解决方案2】：

您可以创建指向每个枚举项的链接。所有项目都将在 javadocs 中列出到 enum 类。

/**
 *  Colors that can be used
 *  {@link #RED}
 *  {@link #BLUE}
 */
public enum Color {

    /**
     * Red color
     */
     RED,

    /**
     * Blue color
     */
    BLUE
}

【讨论】：

表示在通用枚举描述中枚举字段需要重复。不要认为这是个好主意。