Getting Android enum descriptions to appear in JavaDoc

Question

I have defined a custom attribute in xml that must take an enum value as a parameter. The JavaDoc that is automatically produced from my application's R.attr builds a table with enum name and value, but filling in the description column eludes me. How do I define a description that will appear in the JavaDoc?

An example attribute with enum constants:

<declare-styleable name="MyCustomView">
    <attr name="directions">
        <enum name="up" value="0" />
        <enum name="down" value="1" />
        <enum name="left" value="2" />
        <enum name="right" value="3" />
    </attr>
</declare-styleable>

To show what I mean, the JavaDoc for directionPriority in android.R.attr has a table for all the possible enums with "constant," "value" and "description" all filled in.

I have done a good deal of research and tried trial-and-error guesses at a tag that might allow me to include a description, but to no avail. Does anyone know the proper way to document this?

Answer 1

The solution is to add comments before each of the enums. These comments are automatically translated into the enum description column.

<declare-styleable name="MyCustomView">
    <attr name="directions">
        <!-- Go up! -->
        <enum name="up" value="0" />
        <!-- Go down! -->
        <enum name="down" value="1" />
        <!-- Go left! -->
        <enum name="left" value="2" />
        <!-- Go right! -->
        <enum name="right" value="3" />
    </attr>
</declare-styleable>