Wie generierte Klassen Javadoc aus XML-Schemadokumentation enthalten

Question

Ich arbeite derzeit mit einem XML-Schema, das <xsd:annotation>/<xsd:documentation> für die meisten Typen und Elemente hat. Wenn ich Java Beans aus diesem XML-Schema erzeuge, enthält das Javadoc dieser Beans nur einige generisch generierte Informationen über den erlaubten Inhalt des Typs/Elements.

Ich mag würde den Inhalt des <xsd:documentation>-Tag an den entsprechenden Stellen (zum Beispiel der Gehalt an diesem Tag für einen complextType in der Javadoc der Klasse auftauchen sollte erzeugt, dass complex darzustellen) zu sehen.

Gibt es eine Möglichkeit, dies zu erreichen?

Bearbeiten: Dieses XML-Schema wird in einer WSDL mit JAX-WS verwendet, daher könnte dieses Tag auch geeignet sein.

Bearbeiten 2: Ich habe über <jxb:javadoc> gelesen. Soweit ich weiß kann ich das entweder in einer separaten JAXB-Binding-Datei oder direkt im XML-Schema angeben. Das würde mein Problem fast lösen. Aber ich würde lieber das existierende <xsd:documentation>-Tag verwenden, da Javadoc nicht das primäre Ziel der Dokumentation ist (es sind primär Informationen über die Datenstruktur und nicht über die daraus generierten Java-Beans) und nicht-JAXB-Tools den Zugriff auf die Informationen erlauben auch. Das Bereitstellen der Dokumentation sowohl in <jxb:javadoc> als auch in "fühlt sich falsch an, weil ich Daten vervielfältige (und arbeite) ohne triftigen Grund.

bearbeiten 3: Dank der Antwort von Pascal erkannte ich, dass ich die Hälfte haben bereits eine Lösung: Die <xsd:documentation> von complexType s zu Beginn seiner Javadoc geschrieben! Das Problem ist immer noch, dass nurcomplexType s verwendet wird und simpleType s (die auch in einer Klasse führen können) und Elemente sind immer noch Javadoc-weniger.

Answer 1

Ich konnte nie normale xsd:documentation in die Java-Quelle außer platziert werden, wenn und nur wenn war es ein komplexer Typ. Dokumentation für Elemente, einfache Typen, usw. werden ignoriert.

Also, ich am Ende mit jxb:javadoc. Fügen Sie dazu die Definition xmlns:jxb="http://java.sun.com/xml/ns/jaxb" in Ihr <xsd:schema> Element ein.

ein Kind zu <xsd:complexType> hinzufügen oder <xsd: element> oder <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> 

Wo XXX entweder "Klasse" oder "Eigentum" ist.

Für ein Paket, das Sie ein Kind zu xsd:schema schreiben

<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> 

Schreiben von HTML-Dokument mit <![CDATA[ --- ]]>

(EDIT Bracketing erfordert: Während meine Antwort zu schreiben, ist die Frage nach der OP bearbeitet worden, so bin ich Ich aktualisierte es entsprechend)

In meinem Fall war Javadoc das einzige Ziel, so dass es akzeptabel war, jxb:javadoc zu verwenden. Aber Ihr Update macht Sinn und ich stimme Ihnen wirklich zu.Leider habe ich nie eine ideale Lösung für die Situation gefunden, die du beschreibst (also werde ich diese Frage sehr genau befolgen). Vielleicht könnten Sie etwas wie xframe verwenden, um Dokumentation von xsd:documentation zu generieren, aber das beantwortet die Frage nicht.

Answer 2

Dies ist mit der JAXB-Referenzimplementierung nicht möglich. Selbst wenn Sie versuchen würden, ein XJC-Plugin zu schreiben, würden Sie feststellen, dass die API des Plugins keinen Verweis auf die Schema-Definition erhält. Daher gibt es keine Möglichkeit, diese Informationen zu extrahieren.

Unsere einzige Hoffnung ist, dass eine zukünftige Version von JAXB die Situation behebt. Es gibt eine open feature request here.

Answer 3

Ich finde die folgenden Techniken ziemlich gut zum Hinzufügen von JavaDoc-Header zu Java-Elementklassen (generiert aus XML-Schemas). Ich schachtle das JavaDoc in Tags, die im jax-b-Namespace definiert sind und in den XML-Schema-Annotations- und appinfo-Tags verschachtelt sind. Beachten Sie, dass der Jaxb-Namespace Arten von Dokumentations-Tags definiert. Ich benutze zwei von dort: die Klasse und die Eigenschaft-Tags. Definiert im folgenden Namespace: xmlns: jxb = "http://java.sun.com/xml/ns/jaxb"

1) Um eine Klasse zu dokumentieren, verwende ich ein Jaxb "Klasse" -Tag in der folgenden Reihenfolge :

<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) ein Element, um zu dokumentieren, I den "Eigentum" tag wie folgt verwenden:

 <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) I den gleichen Satz von Tags verwenden Attribute zu dokumentieren:

 <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) Um eine Auswahl zu dokumentieren, verwende ich die Eigenschaft jaxb tag und dokumentiere die Auswahl.

<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> 

Der Versuch, die einzelnen Entscheidungen hier scheitern würde, da dieser Tag zu dokumentieren erzeugt eine nicht typisierte Liste.