XML Schema: несколько смежных хз: документация элементы внутри хз: аннотирования

Question

Ищу на XMLSCHEMA * .xsd файл и увидеть формы, как следующие:

 <xs:element name="shortName" type="vr:ShortName" minOccurs="0"> 
     <xs:annotation> 
      <xs:documentation> 
      blah blah blah ... 
      </xs:documentation> 
      <xs:documentation> 
       blah blah blah ... 
      </xs:documentation> 
      <xs:documentation> 
       blah blah blah ... 
      </xs:documentation> 
     </xs:annotation> 
    </xs:element> 

То есть, смежных хз: документация элементов в пределах xs: аннотация элемент.

Я не знаю, какой смысл я должен приписывать такой форме или как это отличается от одного xs: documentation. Предположительно, инструмент может отображать различные элементы документации в виде отдельных абзацев, но не является ли такой смешанной логикой представления, при которой логическая структура не поощряется?

Answer 1

Имеются в наличии несколько элементов xs:documentation внутри того же xs:annotation. Это может иметь смысл использовать несколько элементов при наличии документации на нескольких языках:

<xs:element name="shortName" type="vr:ShortName" minOccurs="0"> 
    <xs:annotation> 
     <xs:documentation xml:lang="en"> 
     This is the documentatin in English ... 
     </xs:documentation> 
     <xs:documentation xml:lang="it"> 
      Questa e' la documentazione in italiano ... 
     </xs:documentation> 
    </xs:annotation> 
</xs:element> 

Вы также можете увидеть несколько xs:documentation элемент в XSDs сгенерированных автоматически с помощью инструмента. Типичная причина этого заключается в том, что инструмент фиксирует информацию пользователя на разных уровнях и по разным причинам, которые возникают при объединении компонентов схемы и ее аннотации. Тогда имеет смысл, по крайней мере, для средства реализации инструмента, поддерживать такое разделение контента с использованием разной разметки.

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

xs:documentation элементы могут содержать произвольный XML, а не только текст. Это означает, что обычно форматирование для документации визуализируется с некоторой разметкой внутри узлов xs:documentation - например. используя <p>...</p> для обозначения абзацев.

[Ответ дополненное/совершенствовалась на основе информации, предоставленной Петру Gardea в комментарии]