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&#39;s no way around that.

Personally I don&#39;t have a problem with the code the way you&#39;ve presented it.  Seems like a perfectly reasonable way to document an enum to me.

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 (&quot;`Something values are used to indicate which mode of operation a client wishes...`&quot;) and each enum value gets a Javadoc description of its purpose and function (&quot;`FIRST_THING indicates that the operation should evaluate the first argument first..`&quot;).

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.

There is a google code search online tool -- http://www.google.com/codesearch

I try to lookup stuff by doing something like [&quot;lang:java public enum&quot;][1]

[An example from Sun][2]


  [1]: http://www.google.com/codesearch#search&amp;q=lang:java+public+enum
  [2]: http://www.google.com/codesearch#search&amp;q=public+enum+lang:java+show:C2YXOCVDRYM:BdNY19GPXpI:C2YXOCVDRYM

We&#39;ve all seen in-browser rich text editors, which allow you to edit colored/styled text in a WYSIWYG manner. But what about code editors, which automatically highlight code based on language rules as you type? Think Eclipse in a textarea (but without the refactoring support).

Do such things exist? I imagine scaling would be a problem - larger files would be difficult  to edit efficiently.

Is there a good in-browser code editor?

What&#39;s the easiest way to get the UTC offset in PHP, relative to the current (system) timezone?

UTC Offset in PHP

I&#39;ve just started using Java&#39;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?

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:
<pre><code class="hljs language-arduino">/**
* Doc for enum
*/
public enum Something {
/**
* First thing
*/
FIRST_THING,
/**
* Second thing
*/
SECOND_THING;
//could continue with more
}
</code></pre>
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?

[Ryan Delucchi][1] asked [here][2] in comment #3 to [Tom Hawtin][3]&#39;s answer:

&gt; why is Class.newInstance() &quot;evil&quot;?

this in response to the code sample:

    // Avoid Class.newInstance, for it is evil.
    Constructor&lt;? extends Runnable&gt; ctor = runClass.getConstructor();
    Runnable doRun = ctor.newInstance();

so, why is it Evil?
  [1]: https://stackoverflow.com/users/9931/ryan-delucchi
  [2]: https://stackoverflow.com/questions/194698/how-to-load-a-jar-file-at-runtime#194712
  [3]: https://stackoverflow.com/users/4725/tom-hawtin-tackline

Why is Class.newInstance() &quot;evil&quot;?

Some ways to iterate through the characters of a string in Java are:

 1. Using `StringTokenizer`?
 2. Converting the `String` to a `char[]` and iterating over that.
 
What is the easiest/best/most correct way to iterate? 

What is the easiest/best/most correct way to iterate through the characters of a string in Java?

I&#39;m having performance oddities with Java2D. I know of the sun.java2d.opengl VM parameter to enable 3D acceleration for 2D, but even using that has some weird issues. 

Here are results of tests I ran:

Drawing a 25x18 map with 32x32 pixel tiles on a JComponent&lt;br&gt;
Image 1 = .bmp format, Image 2 = A .png format

Without -Dsun.java2d.opengl=true
--------------------------------
120 FPS using .BMP image 1&lt;BR&gt;
13 FPS using .PNG image 2

With -Dsun.java2d.opengl=true
-----------------------------
12 FPS using .BMP image 1&lt;BR&gt;
700 FPS using .PNG image 2

Without acceleration, I&#39;m assuming some kind of transformation is taking place with every drawImage() I do in software, and is pulling down the FPS considerably in the case of .PNG. Why though, with acceleration, would the results switch (and PNG actually performs incredibly faster)?! Craziness!

.BMP Image 1 is translated to an image type of TYPE_INT_RGB. .PNG Image 2 is translated to an image type of TYPE_CUSTOM. In order to get consistent speed with and without opengl acceleration, I have to create a new BufferedImage with an image type of TYPE_INT_ARGB, and draw Image 1 or Image 2 to this new image. 

Here are the results running with that:

Without -Dsun.java2d.opengl=true
--------------------------------
120 FPS using .BMP image 1&lt;BR&gt;
120 FPS using .PNG image 2

With -Dsun.java2d.opengl=true
-----------------------------
700 FPS using .BMP image 1&lt;BR&gt;
700 FPS using .PNG image 2

My real question is, can I assume that TYPE_INT_ARGB will be the native image type for all systems and platforms? I&#39;m assuming this value could be different. Is there some way for me to get the native value so that I can always create new BufferedImages for maximum performance? 

Thanks in advance...






Java2D Performance Issues

Is it possible to set a default value for columns in JPA, and if, how is it done using annotations?

Setting default values for columns in JPA

So, I understand &lt;i&gt;that&lt;/i&gt; the following doesn&#39;t work, but &lt;i&gt;why&lt;/i&gt; doesn&#39;t it work?

    interface Adapter&lt;E&gt; {}
    
    class Adaptulator&lt;I&gt; {
    	&lt;E, A extends I &amp; Adapter&lt;E&gt;&gt; void add(Class&lt;E&gt; extl, Class&lt;A&gt; intl) {
    		addAdapterFactory(new AdapterFactory&lt;E, A&gt;(extl, intl));
    	}
    }



The &lt;code&gt;add()&lt;/code&gt; method gives me a compile error, &quot;Cannot specify any additional bound Adapter&amp;lt;E&amp;gt; when first bound is a type parameter&quot; (in Eclipse), or &quot;Type parameter cannot be followed by other bounds&quot; (in IDEA), take your pick.

Clearly you&#39;re just Not Allowed to use the type parameter &lt;code&gt;I&lt;/code&gt; there, before the &lt;code&gt;&amp;amp;&lt;/code&gt;, and that&#39;s that. (And before you ask, it doesn&#39;t work if you switch &#39;em, because there&#39;s no guarantee that &lt;code&gt;I&lt;/code&gt; isn&#39;t a concrete class.) But why not? I&#39;ve looked through Angelika Langer&#39;s FAQ and can&#39;t find an answer.

Generally when some generics limitation seems arbitrary, it&#39;s because you&#39;ve created a situation where the type system can&#39;t actually enforce correctness. But I don&#39;t see what case would break what I&#39;m trying to do here. I&#39;d say maybe it has something to do with method dispatch after type erasure, but there&#39;s only one &lt;code&gt;add()&lt;/code&gt; method, so it&#39;s not like there&#39;s any ambiguity...

Can someone demonstrate the problem for me?


Why can&#39;t I use a type argument in a type parameter with multiple bounds?

Suppose we have some named enums:

    enum MyEnum {
          FOO,
          BAR = 0x50
    };

What I googled for is a script (any language) that scans all the headers in my project and generates a header with one function per enum.

    char* enum_to_string(MyEnum t);

And a implementation with something like this:

    char* enum_to_string(MyEnum t){
          switch(t){
             case FOO:
                return &quot;FOO&quot;;
             case BAR:
                return &quot;BAR&quot;;
             default:
                return &quot;INVALID ENUM&quot;;
          }
     }

The gotcha is really with typedefed enums, and unnamed C style enums. Does anybody know something for this?

EDIT: The solution should not modify my source, except for the generated functions. The enums are in an API, so using the solutions proposed until now is just not an option.

Is there a simple way to convert C++ enum to string?

Getting the max value of an enum

I have a bunch of enum types in some library header files that I&#39;m using, and I want to have a way of converting enum values to user strings - and vice-versa. 

RTTI won&#39;t do it for me, because the &#39;user strings&#39; need to be a bit more readable than the enumerations.

A brute force solution would be a bunch of functions like this, but I feel that&#39;s a bit too C-like.

    enum MyEnum {VAL1, VAL2,VAL3};
    
    String getStringFromEnum(MyEnum e)
    {
      switch e
      {
      case VAL1: return &quot;Value 1&quot;;
      case VAL2: return &quot;Value 2&quot;;
      case VAL1: return &quot;Value 3&quot;;
      default: throw Exception(&quot;Bad MyEnum&quot;);
      }
    }


I have a gut feeling that there&#39;s an elegant solution using templates, but I can&#39;t quite get my head round it yet.


**UPDATE:** Thanks for suggestions - I should have made clear that the enums are defined in a third-party library header, so I don&#39;t want to have to change the definition of them.

My gut feeling now is to avoid templates and do something like this:


    char * MyGetValue(int v, char *tmp); // implementation is trivial
    
    #define ENUM_MAP(type, strings) char * getStringValue(const type &amp;T) \
     { \
     return MyGetValue((int)T, strings); \
     }
    
    ; enum eee {AA,BB,CC}; - exists in library header file 
    ; enum fff {DD,GG,HH}; 
    
    ENUM_MAP(eee,&quot;AA|BB|CC&quot;)
    ENUM_MAP(fff,&quot;DD|GG|HH&quot;)

    // To use...

		eee e;
		fff f;
		std::cout&lt;&lt; getStringValue(e);
		std::cout&lt;&lt; getStringValue(f);


How to easily map c++ enums to strings

I thought I understood Java generics pretty well, but then I came across the following in java.lang.Enum:

    class Enum&lt;E extends Enum&lt;E&gt;&gt;

Could someone explain how to interpret this type parameter? Bonus points for providing other examples of where a similar type parameter could be used.

Java Enum definition

What is the best way to save enums into a database?

I know Java provides `name()` and `valueOf()` methods to convert enum values into a String and back. But are there any other (flexible) options to store these values?

Is there a smart way to make enums into unique numbers (`ordinal()` is not safe to use)?

**Update:**

Thanks for all awesome and fast answers! It was as I suspected.

However a note to &#39;toolkit&#39;; That is one way. The problem is that I would have to add the same methods to each Enum type I create. Thats a lot of duplicated code and, at the moment, Java does not support any solutions for this (a Java enum cannot extend other classes).

Ways to save enums in database

Should I be writing Doc Comments for all of my java methods? 

Do you use Javadoc for every method you write?

I am using Maven (and the Maven Eclipse Integration) to manage the dependencies for my Java projects in Eclipse. The automatic download feature for JAR files from the Maven repositories is a real time saver. Unfortunately, it does not include API documentation and source code.

How can I set up Maven to automatically also get the source and javadoc attachments and register them properly with Eclipse?

Get source jar files attached to Eclipse for Maven-managed dependencies

I have a small code example I want to include in the Javadoc comment for a method.  

    /**
     * -- ex: looping through List of Map objects --
     * &lt;code&gt;
     * for (int i = 0; i &lt; list.size(); i++) {
     *      Map map = (Map)list.get(i);
     *      System.out.println(map.get(&quot;wordID&quot;));
     *      System.out.println(map.get(&quot;word&quot;));
     * }
     * &lt;/code&gt;
     * 
     * @param query - select statement
     * @return List of Map objects
     */

The problem is the code example shows up in the Javadoc with no line breaks making it hard to read.  
    
    -- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get(&quot;wordID&quot;)); System.out.println(map.get(&quot;word&quot;)); } 
    Parameters
    query - - select statement 
    Returns:
    List of Map objects 

I guess I am wrong in assuming the code tag would handle line breaks.  What is the best way to format code examples in Javadoc comments ?

Multiple line code example in Javadoc comment

Is there a reason to include both `@version` and `@since` as part of a class?

They seem to be mutually exclusive.

Also, what does `%I%` and `%G%`  mean, and how to set/use them?

     @version %I%, %G%

javadoc: @version and @since

In the Java APIs I can see Javadoc comments for packages.

How/where do I place Javadoc comments to document a package?

Content Type	Original Author	Original Content on Stackoverflow
Question	MetroidFan2002	View Question on Stackoverflow
Solution 1 - Java	Mike Deck	View Answer on Stackoverflow
Solution 2 - Java	Dov Wasserman	View Answer on Stackoverflow
Solution 3 - Java	anjanb	View Answer on Stackoverflow

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

Java Problem Overview

Java Solutions

Solution 1 - Java

Solution 2 - Java

Solution 3 - Java

UTC Offset in PHP

Is there a good in-browser code editor?

Attributions