Menu
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?
784
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.
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.
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.
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/.)
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.
132
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.
36
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
