如何为类的单独枚举值编写Javadoc文档

Question

我正在为一个包含枚举的类编写 Javadoc。是否有一种方法可以为单独的枚举生成 Javadoc？例如，现在我有像这样的东西：

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

然而，这只记录了所有枚举的整体：

有没有一种方法可以逐个记录每个HairColor值？ 而不必将枚举移动到其自己的类中或更改为非枚举类型？

- Snowy Coder Girl

---

出于好奇，你为什么想这样做？你将枚举列为 private 嵌套枚举，所以你的类的用户无法使用该枚举或其值。如果它是公共和独立的，那么将其文档化为自己的单元有什么大不了的呢？ - Mark Peters

在我的实际代码中，它是公共的。你知道公司的标准可能是怎样的。“这样做会更好”“太糟糕了，虽然我们对编程一无所知，但我们认为你应该按照我们的方式去做”。哈哈 - Snowy Coder Girl

好的。只要确保告诉他们，由于文档的不可移动要求，发布将被推迟一周，这些文档可能永远不会被阅读。这通常会引起关心业务的人的注意。 - Mark Peters

Javadoc在使用上相对较少，但我喜欢用来编码。有些程序员的方法名与实际情况无关。例如，getCat返回过去10天里所有爬树的猫，但不包括星期二或节假日。哈哈 - Snowy Coder Girl

@RachelG。每个开发人员都认为自己比其他开发人员优秀，这是一个相当普遍的现象。不过并无冒犯之意。 - OddDev

@OddDev 是的，我想这有点像开车吧。没有人认为自己是个糟糕的司机。但有些人显然就是。哈哈。我只是想指出一些开发人员不遵循最佳实践，比如使用描述性名称等。 - Snowy Coder Girl

Answer 1

你可以像处理其他变量一样来处理它，就像你使用javadoc一样。

/**
 * 可使用的颜色
 */
public enum Color
{
    /**
     * 红色
     */
    red,
/**
     * 蓝色
     */
    blue

}

编辑：

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

- user489041

---

这将生成相同的内容（请注意快照上的链接）。我希望直接将它们放在类javadoc中（而不是链接到另一个javadoc）。但还是谢谢 =）+1为推进问题描述。 - Snowy Coder Girl

@Rachel：枚举是一个独立的类。你不能在封闭类中包含它的完整文档（至少不能在不打补丁的标准文档生成器下这样做）。 - Paŭlo Ebermann

是的。当链接发生时，我有点担心它就是这样。我想唯一包含各个枚举的方法就是将其更改为内部类，然后在那里声明对象并编写Java文档。 - Snowy Coder Girl

@user489041：您能否在答案中加入重要的评论（例如我的评论），以供将来参考？ - Paŭlo Ebermann

如果您想引用它，您可以始终使用 {@link Color} 或者例如{@link Color#red}，或者在同一文档中从任何其他javadoc（包括类javadoc）中使用{@link #red}。 - flungo

Answer 2

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

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

    /**
     * Red color
     */
     RED,

    /**
     * Blue color
     */
    BLUE
}

- shushper

---

这意味着枚举字段需要在常见的枚举描述中进行复制。不要认为这是一个好主意。 - AlexMakarov

Answer 3

使用 @see 注解

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

    /**
     * Red color
     */
     RED,

    /**
     * Blue color
     */
    BLUE
}

- Falchio