Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

What is the best way to use JavaDoc to document a Java enum?

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.

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?

like image 784
MetroidFan2002 Avatar asked Oct 12 '08 02:10

MetroidFan2002


People also ask

How do I document an enum?

Documenting an Enum. In order to document an enum in Swagger, we need to declare the models using annotation @ApiModel. In this example, we created an enum Role with four possible values – Engineer, Clerk, Driver, and Janitor. As we need to document this enum, we'll add @ApiModel to the enum Role.

How do I document a Javadoc?

From the main menu, select Tools | Generate JavaDoc. In the dialog that opens, select a scope — a set of files or directories for which you want to generate the reference, and set the output directory where the generated documentation will be placed.

How do you write an effective Javadoc?

The correct approach is an @param tag with the parameter name of <T> where T is the type parameter name. There should be one blank line between the Javadoc text and the first @param or @return. This aids readability in source code. The @param and @return should be treated as phrases rather than complete sentences.

What is Javadoc style documentation?

Javadoc is a documentation tool which defines a standard format for such comments, and which can generate HTML files to view the documentation from a web broswer. (As an example, see Oracle's Javadoc documentation for the Java libraries at http://download.oracle.com/javase/6/docs/api/.)


2 Answers

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.

like image 132
Mike Deck Avatar answered Sep 29 '22 22:09

Mike Deck


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).

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..").

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.

like image 36
Dov Wasserman Avatar answered Sep 29 '22 23:09

Dov Wasserman