Adding documentation to layout file

Issue

I'm looking for a way to document a layout file to improve its reusability. What I'd like is something that produces javadoc in generated R file like this.

I know it is possible to do so when using <declare-styleable>. This :

<declare-styleable name="myStyleable">
    <!-- Some comment -->
    <attr name="someAttr" format"color" />
</declare-styleable>

Produces this output i'd like to obtain for layout files without success :

public final class R {
    /** Some comment */
    public static final int someAttr...
}

Does someone know of the mean to achieve this ? I'm interrested in :

• Documenting the layout file, so that documentation be available when using R.layout.my_layout
• Documenting a particular element of the file, so that the documentation be available when finding it by id f.e. aView.findViewById(R.id.the_id_that_is_documented)

Solution

By the way, I found part of the response : for ids it is possible to add comments if the id is defined in a resource file (in res/values) :

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- This is a comment -->
    <item name="myId" type="id"></item>    
</resources>

Will produce this result in R.class :

public final class R {
    public static final class id {
    /**  This is a comment 
     */
    public static int myId=0x7f050007;
}

This won't work directly in the layout file if you use @+id/some_cute_id

---

Edit : and here's the answer for layout files. In fact it might work for everything (Found it browsing sdk sources in res/values/public.xml). This :

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- 
         * This layout contains a list that enables to choose a bluetooth device to pair with among paired ones -->
    <public type="layout" name="devices_choose" id="0x7f030005" />    
</resources>

Produces this output in R :

public final class R {
    public static class layout {
        /**  
         * This layout contains a list that enables to choose a bluetooth device to pair with among paired ones 
         */
        public static final int devices_choose=0x7f030005;
    }
}

Answered By - Antoine Marques