Ответ 1

Я бы написал файл XML Schema (XSD), чтобы определить структуру XML-документа. Теги xs:annotation и xs:documentation могут быть включены для описания элементов. XSD файл можно преобразовать в документацию с использованием таблиц стилей XSLT, таких как xs3p или такие инструменты, как XML Schema Documenter.

Введение в XML-схему см. в учебном пособии XML Schools.

Вот ваш пример, выраженный как XML-схема с тегами xs:annotation:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="objectroot">
    <xs:complexType>
      <xs:sequence>

        <xs:element name="v" type="xs:string">
          <xs:annotation>
            <xs:documentation>Current version of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

        <xs:element name="label" minOccurs="0" maxOccurs="unbounded" type="xs:string">
          <xs:annotation>
            <xs:documentation>Name of the object from the repository.</xs:documentation>
          </xs:annotation>
        </xs:element>

      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Ответ 2

Вы можете попытаться документировать его, создав схему XSD, которая предоставит более формальную спецификацию вашего XML. Многие инструменты генерируют XSD для вас из образца XML в качестве отправной точки.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="objectroot">
  <xs:complexType>
    <xs:sequence>
      <xs:element name="v" minOccurs="1" type="xs:string"/> <!-- current version -->
      <xs:element name="label" type="xs:string"/> <!-- object name -->
    </xs:sequence>
  </xs:complexType>
</xs:element>
</xs:schema>

Ответ 3

Наслаждайтесь компактным синтаксисом RELAX NG

Экспериментируя с различными языками схем XML, я нашел RELAX NG наиболее подходящим для большинства случаев (рассуждение в конце).

Требования

• Разрешить документирование структуры документа XML
• Сделайте это в удобочитаемой форме
• Держите его простым для автора

Измененный образец XML (doc.xml)

Я добавил один атрибут, чтобы проиллюстрировать этот тип структуры в документации.

<objectRoot created="2015-05-06T20:46:56+02:00">
    <v>
        <!-- Current version of the object from the repository. !-->
        <!-- (Occurance: 1) -->
    </v>
    <label>
        <!-- Name of the object from the repository. !-->
        <!-- (Occurance: 0 or 1 or Many) -->
    </label>
</objectRoot>

Используйте синтаксис RELAX NG Compact с комментариями (schema.rnc)

RELAX NG позволяет описывать образец XML-структуры следующим образом:

start =

## Container for one object
element objectRoot {

    ## datetime of object creation
    attribute created { xsd:dateTime },

    ## Current version of the object from the repository
    ## Occurrence 1 is assumed by default
    element v {
        text
    },

    ## Name of the object from the repository
    ## Note: the occurrence is denoted by the "*" and means 0 or more
    element label {
        text
    }*
}

Я думаю, очень сложно победить простоту, сохраняя данный уровень выразительности.

Как прокомментировать структуру

• всегда помещайте комментарий до соответствующего элемента, а не после него.
• для чтения, используйте одну пустую строку перед блоком комментариев.
• использовать префикс ##, который автоматически преобразуется в элемент документации в другом формате схемы. Единый хэш # преобразуется в комментарий XML, а не элемент документации.

• несколько последовательных комментариев (как в примере) превратятся в одну строку многострочной документации в пределах одного элемента.

• Очевидный факт: встроенные комментарии XML в doc.xml не имеют значения, только то, что находится в schema.rnc.

Если требуется XML Schema 1.0, сгенерируйте его (schema.xsd)

Предполагая, что у вас есть инструмент с открытым исходным кодом под названием trang, вы можете создать файл XML-схемы следующим образом:

$ trang schema.rnc schema.xsd

Результирующая схема выглядит следующим образом:

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="objectRoot">
    <xs:annotation>
      <xs:documentation>Container for one object</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="v"/>
        <xs:element minOccurs="0" maxOccurs="unbounded" ref="label"/>
      </xs:sequence>
      <xs:attribute name="created" use="required" type="xs:dateTime">
        <xs:annotation>
          <xs:documentation>datetime of object creation</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name="v" type="xs:string">
    <xs:annotation>
      <xs:documentation>Current version of the object from the repository
Occurance 1 is assumed by default</xs:documentation>
    </xs:annotation>
  </xs:element>
  <xs:element name="label" type="xs:string">
    <xs:annotation>
      <xs:documentation>Name of the object from the repository
Note: the occurance is denoted by the "*" and means 0 or more</xs:documentation>
    </xs:annotation>
  </xs:element>
</xs:schema>

Теперь ваши клиенты, настаивая на использовании только XML Schema 1.0, используют вашу спецификацию документа XML.

Проверка doc.xml на schema.rnc

Существуют инструменты с открытым исходным кодом, такие как jing и rnv, поддерживающие синтаксис RELAX NG Compact и работающие как с Linux, так и с MS Windows.

Примечание: эти инструменты довольно старые, но очень стабильные. Прочитайте это как признак стабильности не как признак устаревания.

Использование jing:

$ jing -c schema.rnc doc.xml

-c важен, jing по умолчанию принимает RELAX NG в форме XML.

Используя rnv для проверки, сам schema.rnc:

$ rnv -c schema.rnc

и проверить doc.xml:

$ rnv schema.rnc doc.xml

rnv позволяет одновременно проверять несколько документов:

$ rnv schema.rnc doc.xml otherdoc.xml anotherone.xml

RELAX NG Компактный синтаксис - профи

• очень читаемый, даже новичок должен понимать текст
• легко учиться (RELAX NG поставляется с хорошим учебным пособием, его можно узнать в течение одного дня).
• очень гибкий (несмотря на то, что он выглядит просто, он охватывает многие ситуации, некоторые из них не могут быть даже решены с помощью XML Schema 1.0).
• существуют некоторые инструменты для преобразования в другие форматы (форма RELAX NG XML, XML Schema 1.0, DTD, но даже генерация образца XML-документа).

Ограничения RELAX NG

• множественность может быть только "ноль или один", "только один", "ноль или более" или "один или несколько". (Множественность небольшого числа элементов может быть описана "глупым повторением" "нулевого или одного" определения)
• Существуют конструкции XML Schema 1.0, которые не могут быть описаны RELAX NG.

Выводы

Для требования, указанного выше, синтаксис RELAX NG Compact выглядит наилучшим образом. С RELAX NG вы получаете обе - читаемую человеком схему, которая даже пригодна для автоматической проверки.

Существующие ограничения не вступают в силу очень часто и могут быть во многих случаях разрешены комментариями или другими способами.

Ответ 4

Лично я бы предпочел увидеть его в XML (2-й путь).

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

Ответ 5

Отображение в таблице имеет свои ограничения, например. mulit-levels вложенных детей, но для простой структуры XML я думаю, что все будет хорошо. Для чего-либо, имеющего более одного вложенного уровня, я предпочел бы путь XML.

Еще лучший способ - создать файл XML Schema (XSD). Таким образом, вы получаете преимущества видеть его в XML, и вы можете проверить файл после того, как данные будут введены в файл схемы с помощью некоторого программного обеспечения.

Для большой серии руководств по XSD проверьте w3schools - Учебное пособие по XML-схеме

Ответ 6

Я просто хочу добавить еще одну вещь, если кто-то найдет ее полезной. Я иногда программирую в HTML и других случаях в android. Когда я делаю HTML, я документирую свой пользовательский XML в том же формате, что и W3Schools, как в http://www.w3schools.com/tags/att_a_href.asp, если это проект андроида, над которым я работаю затем я следую стандартам Google, как в http://developer.android.com/guide/topics/manifest/activity-element.html#screen
Таким образом, программисты, с которыми я работаю, не должны выполнять какую-либо дополнительную работу, чтобы понять мою документацию.