java - Android 中是否有自定义 XML 样式属性的文档标准？

Question

我能够记录我的 Android 项目中的几乎所有内容，并为它们生成漂亮的 API 引用。

唯一的异常(exception)是 XML 文件，尤其是包含样式属性的属性文件。

例如，res/values/attrs.xml 的一部分:

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

我注意到在 Android 源代码中，standard attributes documentation is generated for R .

显然，我生成的文档包含一些属性类型(在本例中为 boolean 值)的通用文本:

是否有针对此类文档的官方规范或记录源自 XML 的属性以便描述出现在自动生成的 JavaDoc 中的方法？

Answer 1

我不确定这是官方标准，但我在写问题时偶然发现了它。为了其他可能遇到此问题的人，我决定发布问题并回答它。

我能够通过在属性上方添加 XML 注释来生成属性文档，现在我已经看到了，这似乎很明显。

我最初在没有重建我的项目的情况下进行了尝试，这导致了原始文档的缺乏。重建模块并生成 JavaDoc 后，我得到了想要的结果。

要遵循的步骤是:

1. 在所需属性上方添加评论。

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

2. 重建相关模块/项目。

3. 生成 JavaDoc。使用 Android Studio(目前为 0.5.8)。
   当前有一个 small issue对于自动生成，我正在使用第一个链接帖子中介绍的解决方法。
   生成的文档应包含您的意见。
   

如果有人知道这方面的任何官方来源或官方方法，请不要犹豫与他们分享。

更新:
看起来这确实是它在 Android source files 中完成的方式。 ，包括一些 JavaDoc 指令、HTML 和注释中的子注释，例如:

<!-- 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>