Gibt es einen Dokumentationsstandard für benutzerdefinierte XML-Stilattribute in Android?

Question

Ich kann praktisch alles in meinen Android-Projekten dokumentieren und schöne API-Referenzen dafür generieren.

Die einzige Ausnahme sind die XML-Dateien, insbesondere die Attributdateien, die die styleable-Attribute enthalten.

Zum Beispiel ein Teil von res/values/attrs.xml:

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

Meine generierte Dokumentation enthält offensichtlich einen generischen Text für meinen Attributtyp (hier: boolean):

Gibt es eine offizielle Spezifikation für diese Art von Dokumentation oder einen Weg, um Attribute, die in XML erstellt wurden, zu dokumentieren, damit die Beschreibung im automatisch generierten JavaDoc erscheint?

Answer 1

Ich bin mir nicht sicher, ob dies ein offizieller Standard ist, aber ich bin darauf gestoßen, als ich meine Frage geschrieben habe. Ich entschied mich, die Frage trotzdem zu veröffentlichen und zu beantworten, zum Wohle anderer, die auf dieses Problem stoßen könnten.

Ich konnte die Attributdokumentation generieren, indem ich einen XML-Kommentar über dem Attribut hinzufügte, was jetzt ziemlich offensichtlich erscheint, nachdem ich es gesehen habe.

Ich habe es zunächst ohne Neuerstellung meines Projekts versucht, was zum ursprünglichen Mangel an Dokumentation führte. Nachdem ich das Modul neu erstellt und die JavaDoc generiert habe, habe ich das gewünschte Ergebnis erhalten.

Die Schritte, denen zu folgen sind, sind:

1. Platziere einen Kommentar über dem gewünschten Attribut/Attributen.

2. Erneuere das relevante Modul/Projekt.

3. Generiere die JavaDoc. Verwendung von Android Studio (aktuell 0.5.8).
   Aktuell gibt es ein kleines Problem mit der automatischen Generierung, ich verwende den in dem ersten verlinkten Beitrag eingeführten Workaround.
   Die generierte Dokumentation sollte deine Kommentare enthalten.
   

Wenn jemand offizielle Quellen dafür kennt oder eine offizielle Methode, zögern Sie bitte nicht, sie zu teilen.

Update:
Es scheint, dass dies tatsächlich der Weg ist, wie es in den Android-Quelldateien gemacht wird, einschließlich einiger JavaDoc-Anweisungen, HTML und Kindnotizen in den Kommentaren, beispielsweise: