安卓中自定义XML样式属性是否有文档标准？

Question

我能够记录下我Android项目中的几乎所有内容，并为它们生成漂亮的API参考文档。

唯一例外的是XML文件，尤其是包含可定制属性的属性文件。

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

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

我注意到在Android源代码中，针对R标准属性生成了文档。

我的生成的文档里，显然包括了一些通用文本来描述属性类型（这个例子是boolean）： 是否有官方规范来文档化来源于XML的属性，以便其描述能够出现在自动生成的JavaDoc中？

- MasterAM

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）。
   目前存在一个小问题，我正在使用第一篇帖子中介绍的解决方法。
   生成的文档应该包含您的注释。
   

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

更新：
似乎这确实是在Android源文件中执行的方式，其中包括一些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>

- MasterAM

---

你的XML资源的注释是否能够被输出到javadoc或R.java文件中？我正在通过gradle创建javadoc，就像我在类似的问题中所描述的那样，但是默认情况下不会为我的XML资源添加文档：http://stackoverflow.com/questions/35430792/adding-documentation-for-generated-r-java-files-in-android-studio - Petrakeas

@Petrakeas，我最近没有做Android开发，所以我打开了我的原始项目，并更新到最新版本的AndroidStudio（v2.0-beta5）以使其能够正常工作。似乎XML中的数据没有到达R.java，因此无法进入JavaDoc，因此它不像以前那样工作。在这个过程中，我得到了很多“@attr是未知标记”的警告，但我没有时间深入研究它。我没有尝试从gradle生成JavaDoc，也没有尝试过DocLava，但问题可能与这个有关。 - MasterAM

我查看了例如TextView，在源代码（类文档）中，每个XML属性都有一个条目：@attr ref android.R.styleable#TextView_text. 我猜这就是它如何到达类的javadoc中，在“XML属性”部分。然而，当我添加相应的@attr ref mypackage.R.styleable#MyClass_myattr（和myatrr的XML注释），但生成的文档只包含标准文本。此外，控制台上会出现警告：“warning - @attr is an unknown tag.”，但实际上是针对Android类的！ - user905686