Как создать сгенерированные классы, содержащие Javadoc из документации XML-схемы

Question

В настоящее время я работаю с XML-схемой, которая имеет большинство типов и элементов для всех типов и элементов: <xsd:annotation>/<xsd:documentation>. Когда я генерирую Java-компоненты из этой XML-схемы, Javadoc этих Бобов содержит только общую генерированную информацию о разрешенном содержимом типа/элемента.

Я хотел бы видеть содержимое тега <xsd:documentation> в соответствующих местах (например, содержимое этого тега для completextType должно отображаться в Javadoc класса, сгенерированного для представления этого complexType).

Есть ли способ достичь этого?

Редактировать: эта XML-схема будет использоваться в WSDL с JAX-WS, поэтому этот тег также может быть уместным.

Редактировать 2: Я читал около <jxb:javadoc>. Насколько я понимаю, я могу указать это либо в отдельном файле привязки JAXB, либо непосредственно в XML-схеме. Это почти решило бы мою проблему. Но я предпочел бы использовать существующий тег <xsd:documentation>, поскольку Javadoc не является основной целью документации (это информация о структуре данных в первую очередь, а не о Java-компонентах, сгенерированных из нее), а также чтобы инструменты, не относящиеся к JAXB, имели доступ к информации также. Предоставление документации в <jxb:javadoc> и xsd:documentation> «чувствует» неправильно, потому что я дублирую данные (и работаю) без уважительной причины.

Редактировать 3: Благодаря ответ Паскаль, я понял, что у меня уже есть половина решения: <xsd:documentation> из complexType s записываются в начало своего Javadoc! Проблема все еще заключается в том, что только используется complexType s и simpleType s (что также может привести к классу), а элементы по-прежнему остаются без Javadoc-less.

Answer 1

Я никогда не мог получить обычный xsd:documentation, который будет размещен в источнике java, кроме , если и только если это был комплексный тип. Документация для элементов, простых типов, и т. Д. Игнорируется.

Итак, я в конечном итоге использую jxb:javadoc. Для этого включите определение xmlns:jxb="http://java.sun.com/xml/ns/jaxb" в свой элемент <xsd:schema>.

Добавить ребенок <xsd:complexType> или <xsd: element> или <xsd:attribute>:

<xsd:annotation><xsd:appinfo><jxb:XXX><jxb:javadoc> 
    This is my comment for a class/property 
</jxb:javadoc></jxb:XXX></xsd:appinfo></xsd:annotation> 

Где XXX либо "класс" или "собственность".

Для пакета вы пишете ребенок в xsd:schema

<xsd:annotation><xsd:appinfo><jxb:schemaBindings><jxb:package name="com.acme"><jxb:javadoc> 
    This is my comment for a package 
</jxb:javadoc></jxb:package></jxb:schemaBindings></xsd:appinfo></xsd:annotation> 

Написание HTML документа требует брекет с <![CDATA[ --- ]]>

(EDIT: Во время написания моего ответа, вопрос был отредактирован ОП, так что я» m, обновляя его соответственно)

В моем случае javadoc был единственной мишенью, поэтому было приемлемо использовать jxb:javadoc. Но ваше обновление имеет прекрасный смысл, и, на самом деле, я полностью согласен с вами.К сожалению, я никогда не нашел идеального решения для ситуации, которую вы описали (поэтому я буду внимательно следить за этим вопросом). Возможно, вы можете использовать что-то вроде xframe для создания документации от xsd:documentation, но это не отвечает на вопрос.

Answer 2

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

Нашей единственной надеждой является то, что будущая версия JAXB исправляет ситуацию. Есть open feature request here.

Answer 3

Я считаю, что следующие методы очень хорошо подходят для добавления заголовков JavaDoc в классы элементов Java (генерируемые из XML-схем). Я устанавливаю JavaDoc в теги, определенные в пространстве имен jax-b, вложенные в аннотации схемы xml и теги appinfo. Обратите внимание, что пространство имен jaxb определяет типы тегов документации; Я использую два из них: класс и теги свойств. определенном в следующем пространстве имен: xmlns: jxb = "http://java.sun.com/xml/ns/jaxb"

1) Для документирования класса я использую тег класса "jaxb" в следующей последовательности :

<xs:complexType name="Structure"> 
    <xs:annotation> 
     <xs:appinfo> 
      <jxb:class> 
       <jxb:javadoc> 
       Documentation text goes here. Since parsing the schema 
       into Java involves evaluating the xml, I escape all 
       the tags I use as follows &lt;p&gt; for <p>. 
       </jxb:javadoc> 
      </jxb:class> 
     </xs:appinfo> 
    </xs:annotation> 

    . 
    . 
    . 
    </xs:complexType> 

2) документально элемент, я использую "свойство" тега следующим образом:

 <xs:element name="description" type="rep:NamedString"> 
      <xs:annotation> 
      <xs:appinfo> 
       <jxb:property> 
        <jxb:javadoc> 
         &lt;p&gt;Documentation goes here.&lt;/p&gt; 
        </jxb:javadoc> 
       </jxb:property> 
      </xs:appinfo> 
      </xs:annotation> 
     </xs:element> 

3) Я использую тот же набор тегов атрибутов документа:

 <xs:attribute name="name" type="xs:NCName" use="required"> 
      <xs:annotation> 
      <xs:appinfo> 
       <jxb:property> 
        <jxb:javadoc> 
         &lt;p&gt;Documentation goes here.&lt;/p&gt; 
        </jxb:javadoc> 
       </jxb:property> 
      </xs:appinfo> 
      </xs:annotation> 
     </xs:attribute> 

4) Чтобы документировать выбор, я использую тэг jaxb свойства, и я документирую выбор.

<xs:choice maxOccurs="unbounded"> 
      <xs:annotation> 
      <xs:appinfo> 
       <jxb:property> 
        <jxb:javadoc> 
         &lt;p&gt;Documentation goes here.&lt;/p&gt; 
        </jxb:javadoc> 
       </jxb:property> 
      </xs:appinfo> 
      </xs:annotation> 

      <xs:element name="value" type="rep:NamedValue" /> 
      <xs:element name="list" type="rep:NamedList" /> 
      <xs:element name="structure" type="rep:NamedStructure" /> 
     </xs:choice> 

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