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

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

Единственным исключением из этого правила являются файлы XML и особенно файлы атрибутов, которые содержат стилизуемые атрибуты.

Например, часть res / values ​​/ attrs.xml:

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

Я заметил, что в исходном коде Android для R создается стандартная документация по атрибутам .

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

автоматически задокументированное свойство

Существует ли официальная спецификация для этого типа документации или способ документировать атрибуты, происходящие из XML, чтобы описание отображалось в автоматически созданном JavaDoc?


android java xml javadoc documentation-generation
person MasterAM    schedule 13.05.2014    source источник

Ответы (1)


arrow_upward
18
arrow_downward

Не уверен, что это официальный стандарт, но я наткнулся на него, когда писал свой вопрос. Я решил опубликовать вопрос и все равно ответить на него, чтобы другие могли столкнуться с этой проблемой.

Мне удалось сгенерировать документацию по атрибутам, добавив 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. Rebuild the relevant module/project.

  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>
person MasterAM    schedule 13.05.2014
comment
Достигают ли ваши комментарии к ресурсам XML вывода javadoc или R.java? Я создаю javadoc через gradle, как я описываю в аналогичном вопросе, но для моих ресурсов XML добавлена ​​документация по умолчанию: stackoverflow.com/questions/35430792/ - person Petrakeas; 16.02.2016
comment
@Petrakeas, в последнее время я не занимался разработкой под Android, поэтому открыл свой исходный проект и обновил его для работы с последней версией AndroidStudio (v2.0-beta5). Кажется, что данные из XML не достигают R.java и, следовательно, не попадают в JavaDoc, поэтому он не работает так, как раньше. В процессе я получаю много @attr is an unknown tag предупреждений, но у меня нет времени углубляться в это. Я не пытался сгенерировать JavaDoc из gradle и не пробовал DocLava, но проблема может быть связана с этим. - person MasterAM; 18.02.2016
comment
Я смотрел, например, TextView и в источнике (в документе класса) есть запись для каждого атрибута XML: @attr ref android.R.styleable#TextView_text. Я предполагаю, что именно так он попадает в javadoc класса в разделе атрибутов XML. Однако, когда я добавляю соответствующие @attr ref mypackage.R.styleable#MyClass_myattr (и комментарии XML в myatrr), сгенерированный документ содержит только стандартный текст. Далее на консоли появляются предупреждения: warning - @attr - неизвестный тег. но собственно для Android классов! - person user905686; 21.10.2016