Есть ли стандарт документации для пользовательских атрибутов стиля XML в Android?

Я могу документировать практически все в моих проектах для Android и создавать для них привлекательные API-ссылки.

Единственное исключение - файлы XML и особенно файлы атрибутов, которые содержат атрибуты, характерные для стиля.

Моя сгенерированная документация, очевидно, включает в себя некоторый общий текст для моего типа атрибута (в этом случае логический):

Есть ли официальная спецификация для документации этого типа или способ документации атрибутов, происходящих из 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).
В настоящее время существует небольшая проблема с автоматической генерацией, я использую обходной путь, введенный в первый связанный пост.
Сгенерированная документация должна содержать ваши комментарии.

Если кто-либо знает какие-либо официальные источники для этого или официального метода, пожалуйста, не стесняйтесь делиться ими.

Update:
Кажется, это действительно так, как это делается в исходных файлах 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>