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?
Android applications use XML to create layout files. Unlike HTML, XML is case-sensitive, requires each tag be closed, and preserves whitespace.
An <attr> element has two xml attributes name and format . name lets you call it something and this is how you end up referring to it in code, e.g., R. attr. my_attribute . The format attribute can have different values depending on the 'type' of attribute you want.
A style is defined in an XML resource that is separate from the XML that specifies the layout. This XML file resides under res/values/ directory of your project and will have <resources> as the root node which is mandatory for the style file. The name of the XML file is arbitrary, but it must use the . xml extension.
</declare-styleable> </resources> This code declares two custom attributes, showText and labelPosition , that belong to a styleable entity named PieChart . The name of the styleable entity is, by convention, the same name as the name of the class that defines the custom view.
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:
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>
Rebuild the relevant module/project.
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>
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