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

android java documentation-generation xml javadoc

2022-09-03 01:50:52

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

唯一的例外是 XML 文件，尤其是包含可设置样式的属性的属性文件。

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

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

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

显然，我生成的文档包含一些用于我的属性类型的通用文本（在本例中为布尔值）：

auto-documented property

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

答案 1

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

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

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

要遵循的步骤是：

在所需属性上方放置注释。

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

</resources>

重新生成相关模块/项目。
生成 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>

答案 2