How to Javadoc a Class's Individual Enums

Question

I am writing the Javadoc for a class that contains its own enums. Is there a way to generate Javadoc for the individual enums? For example, right now I have something like this:

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

However, this only documents all of the enums as a whole:

The generated Javadoc

Is there any way to document each of the HairColor values individually? Without moving the enum into its own class or changing it from an enum?

Out of curiousity, why do you want to? You have the enum listed as a `private` nested enum, so users of your class can't use the enum or its values anyway. And if it is meant to be public and standalone than what's the big deal in documenting it as its own unit? — Mark Peters, Jul 01 '11 at 15:33
In my actual code, it's public. And you know how company standards can be. "This would be better" "Too bad, we who don't know anything about programming think you should do it this way". Lol — Snowy Coder Girl, Jul 01 '11 at 15:38
Fair enough. Just make sure you tell them that the release will get pushed back by a week because of unmovable requirements for documentation that will probably never be read. That typically pricks up the ears of somebody who cares about the business at all. — Mark Peters, Jul 01 '11 at 15:40
Haha. Javadoc is rather unused as javadoc. But I love it for coding. Some programmers have method names that have nothing to do with what's actually going on. Like getCat returns all the cats who have ran up a tree in the last 10 days, not including Tuesdays or holidays. Haha — Snowy Coder Girl, Jul 01 '11 at 15:43
@RachelG. It's quite a phenomenon that every dev thinks she/he's superior to other devs. No offence though. — OddDev, Jul 18 '16 at 13:06
@OddDev Yeah, it's kind of like driving I guess. No one thinks they are a bad driver. But some people obviously are. Lol. I just meant to refer to how some devs don't follow best practices like descriptive names, etc. — Snowy Coder Girl, Sep 11 '16 at 22:02

user489041 · Accepted Answer · 2011-07-01T18:08:58.543

121

You do it just like any other variable you would javadoc.


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

    /**
     * Blue color
     */
    blue

}

EDIT:

From Paŭlo Ebermann : The enum is a separate class. You can't include its full documentation in the enclosing class (at least, without patching the standard doclet).

edited Jul 01 '11 at 18:08

answered Jul 01 '11 at 15:19

user489041

27,916
55
135
204

2

This generates the same thing (notice the link on the snapshot). I am looking to put them directly in the class javadoc (rather than linking to another javadoc). But thanks =) +1 for advancing the problem description. – Snowy Coder Girl Jul 01 '11 at 15:23
6

@Rachel: The enum is a separate class. You can't include its full documentation in the enclosing class (at least, without patching the standard doclet). – Paŭlo Ebermann Jul 01 '11 at 15:31
Yeah. I was kind of worried that's how it was when the linking was occuring. I guess the only way to include the individual enums would be to change it to an inner class and then declare the objects there and javadoc them. – Snowy Coder Girl Jul 01 '11 at 15:36
@user489041: Could you incorporate the important comments (e.g. my one) in the answer, for future reference? – Paŭlo Ebermann Jul 01 '11 at 18:06
If you want to reference it, you could always use `{@link Color}` or even `{@link Color#red}` for example, or even just `{@link #red}` when in the same document from within any other javadoc, including the class javadoc. – flungo Apr 13 '15 at 10:31

score 86 · Answer 2 · edited Aug 07 '20 at 22:49

86

You can create link to each enum's item. All items will be listed in javadocs to enum class.

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

    /**
     * Red color
     */
     RED,

    /**
     * Blue color
     */
    BLUE
}

edited Aug 07 '20 at 22:49

SolutionFindingBrowser

63
8

answered Apr 24 '14 at 10:52

shushper

1,049
7
10

1

It means that enum fields need to be duplicated in common enum description. Don't think that it is a good idea. – AlexMakarov Dec 29 '20 at 06:56

score 0 · Answer 3 · answered Jul 25 '22 at 11:40

0

With @see anotation

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

    /**
     * Red color
     */
     RED,

    /**
     * Blue color
     */
    BLUE
}

answered Jul 25 '22 at 11:40

Falchio

174
1
14

How to Javadoc a Class's Individual Enums

3 Answers3

Linked