Is there a documentation standard for custom XML style attributes in Android?

Question

I am able to document pretty much everything in in my Android projects and generate nice-looking API references for them.

The only exception to this are the XML files, and especially the attribute files that contain the styleable attributes.

For example, a portion of res/values/attrs.xml:

<resources>
    <declare-styleable name="TimelineView">
        <attr name="drawCollapsed" format="boolean" />
    </declare-styleable>
</resources>

I noticed that in the Android source, standard attributes documentation is generated for R.

My generated documentation, obviously, includes some generic text for my attribute type (boolean, in this case):

Is there an official specification for this type of documentation or a way to document attributes originating in XML such that the description appears in the auto-generated JavaDoc?

Answer 1

I am not sure that this is an official standard, but I stumbled across it when writing my question. I decided to post the question and answer it anyway, for the sake of other who might encounter this issue.

I was able to generate attribute documentation by adding an XML comment above the attribute, which seems quite apparent now that I have seen it.

I initially tried it without rebuilding my project, which lead to the original lack of documentation. Once I rebuilt the module and generated the JavaDoc, I got the desired result.

The steps to follow are:

1. Place a comment above desired attribute(s).

   <resources>
       <declare-styleable name="TimelineView">
           <!-- Initially draw collapsed until adapters have been set. -->
           <attr name="drawCollapsed" format="boolean" />
       </declare-styleable>
   
   </resources>
   

2. Rebuild the relevant module/project.

3. Generate the JavaDoc. Using Android Studio (currently 0.5.8).
   There is currently a small issue with the automatic generation, I am using the workaround introduced in the first linked post.
   The generated documentation should contain your comments.
   

If anyone knows of any official sources for this or an official method, please don't hesitate to share them.

Update:
It seems this is indeed the way it is done in the Android source files, including some JavaDoc directives, HTML and child annotation in the comments, for example:

<!-- Alignment constants. -->
<attr name="alignmentMode">
    <!-- Align the bounds of the children.
    See {@link android.widget.GridLayout#ALIGN_BOUNDS}. -->
    <enum name="alignBounds" value="0" />
    <!-- Align the margins of the children.
    See {@link android.widget.GridLayout#ALIGN_MARGINS}. -->
    <enum name="alignMargins" value="1" />
</attr>