Wie machen generierten Klassen Javadoc von XML-Schema-Dokumentation enthalten

Question

Im Moment arbeite ich mit einem XML-Schema, das <xsd:annotation> / <xsd:documentation> auf die meisten Arten und Elemente. Wenn ich Java Beans aus diesem XML-Schema erzeugen, dann ist die Javadoc dieser Bohnen enthält nur einige generische erzeugten Informationen über den erlaubten Inhalt des Typs / Element.

Ich möchte 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) sehen.

Gibt es eine Möglichkeit, dies zu erreichen?

Bearbeiten . Dieses XML-Schema wird in einem WSDL mit JAX-WS verwendet werden, so könnte diesen Tag als auch angemessen sein

Edit 2 : Ich habe über <jxb:javadoc> lesen. Von dem, was ich verstehe, kann ich festlegen, dass entweder in einem separaten JAXB Einbindemappe oder direkt im XML-Schema. Das wäre mein Problem fast gelöst. Aber ich würde lieber verwenden, um den bestehenden <xsd:documentation> Tag, da Javadoc nicht das primäre Ziel der Dokumentation ist (es ist Informationen über die Datenstruktur in erster Linie und nicht über die Java Beans von ihm erzeugten) und Nicht-JAXB Tool zu ermöglichen, auf die Informationen zuzugreifen auch. Die Bereitstellung der Dokumentation sowohl <jxb:javadoc> und xsd:documentation> „fühlt“ falsch, weil ich dupliziert Daten (und Arbeit) für keinen guten Grund.

Bearbeiten 3 : Dank der Antwort von Pascal Ich erkannte, dass ich schon eine halbe Lösung haben: Die <xsd:documentation> von complexTypes zu Beginn seiner Javadoc geschrieben! Das Problem ist nach wie vor, dass nur , dass complexTypes verwendet wird und simpleTypes (die auch in einer Klasse zur Folge haben kann) und Elemente sind noch Javadoc-less.

Answer 1

Ich habe nie in der Lage gewesen regelmäßige xsd:documentation zu erhalten, mit Ausnahme von in der Java-Quelle gesetzt werden, wenn und nur wenn es ist ein komplexer Typ ist. Dokumentation für Elemente, einfache Typen, etc werden ignoriert.

Also, ich am Ende mit jxb:javadoc. Dazu gehören die Definition von xmlns:jxb="http://java.sun.com/xml/ns/jaxb" in Ihrem <xsd:schema> Element.

Fügen Sie ein Kind <xsd:complexType> 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".

Für ein Paket schreiben Sie ein Kind 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>

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

(EDIT: Während meine Antwort zu schreiben, ist die Frage nach der OP bearbeitet worden, damit ich es dementsprechend bin Aktualisierung)

In meinem Fall war javadoc das einzige Ziel, so dass es akzeptabel war jxb:javadoc zu verwenden. Aber Ihr Update macht Sinn und, tatsächlich, ich bin vollkommen einverstanden mit Ihnen. Leider habe ich nie eine ideale Lösung für die Situation zu finden Sie beschreiben (so werde ich diese Frage folgen sehr sorgfältig). Vielleicht könnten Sie so etwas wie XFrame verwenden Dokumentation von xsd:documentation zu erzeugen, aber diese nicht antwortet die Frage.

Answer 2

Das ist einfach nicht möglich, mit der JAXB Referenzimplementierung. Auch wenn Sie ein XJC Plugin zu schreiben, um zu versuchen, würde man feststellen, dass das Plugin API keinen Hinweis auf die Schema-Definition angegeben ist, so 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 offene Feature-Anfrage hier .

Answer 3

Ich finde die folgenden Techniken ziemlich gut funktionieren JavaDoc Header Java Elementklassen für das Hinzufügen (erzeugt aus XML-Schema). Ich Nest die JavaDoc in Tags in dem JAX-b-Namensraum definiert, in der XML-Schema-Annotation und AppInfo Tags verschachtelt. Beachten Sie die jaxb Namespace Dokumentationstypen Tags definiert; Ich benutze zwei von dort: die Klasse und die Eigenschaft Tags. definiert in den folgenden Namespace: xmlns: JXB = "http://java.sun.com/xml/ns/jaxb"

1) Um eine Klasse zu dokumentieren, verwende ich einen 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) Um ein Element zu dokumentieren, ich den "Eigenschaft" 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) Ich verwende den gleichen Satz von Tags 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 ich dokumentieren die Wahl.

    <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 eine nicht typisierte Liste erzeugt.

Answer 4

Vor allem für den Fall, ich XJC Plugin xjc-Dokumentation-Annotation-Plugin geschrieben .

Was es tut: <annotation><documentation> -> Java-Klasse Anmerkungen

gesagt, wir haben diese Aufgabe in XSD beschrieben:

<xs:complexType name="CadastralBlock">
    <xs:annotation>
        <xs:documentation>Cadastral quarter</xs:documentation>
    </xs:annotation>
    <xs:sequence>
        <xs:element name="number" type="xs:string">
            <xs:annotation>
                <xs:documentation>Cadastral number</xs:documentation>
            </xs:annotation>
        </xs:element>
</xs:complexType>

Wir betreiben xjc wie:

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated scheme.xsd

Und bekam Klasse wie (Getter, Setter und alle der Einfachheit halber weggelassen Anmerkungen):

public class CadastralBlock {
    protected String number;
}

Aber in meinem Fall mag ich bekannt, wie die Klasse und Felder wurden in der Quelldatei mit dem Namen So ist es, was dieses Plugin tun!

So erhalten Sie:

@XsdInfo(name = "Cadastral quarter", xsdElementPart = "<complexType name=\"CadastralBlock\">\n  <complexContent>\n    <restriction base=\"{http://www.w3.org/2001/XMLSchema}anyType\">\n      <sequence>\n        <element name=\"number\" type=\"{http://www.w3.org/2001/XMLSchema}string\"/></sequence>\n      </restriction>\n  </complexContent></complexType>")
public class CadastralBlock {
    @XsdInfo(name = "Cadastral number")
    protected String number;
}

Wie verwenden

Hand Anruf in Kommandozeile

Wenn Sie ausführen möchten es manuell jar-Klasse mit Plug-in laufen Classpath gewährleisten und nur Option -XPluginDescriptionAnnotation hinzufügen. F.e:.

xjc -npa -no-header -d src/main/generated-java/ -p xsd.generated -XPluginDescriptionAnnotation scheme.xsd

Aufruf von Java / Groovy

Driver.run(
    [
        '-XPluginDescriptionAnnotation'
        ,'-d', generatedClassesDir.absolutePath
        ,'-p', 'info.hubbitus.generated.test'
        ,'CadastralBlock.xsd'
    ] as String[]
    ,new XJCListener() {...}
)

Siehe Test XJCPluginDescriptionAnnotationTest zum Beispiel.

Verwendung von Gradle

Mit gradle-xjc-Plugin :

plugins {
    id 'java'
    id 'org.unbroken-dome.xjc' version '1.4.1' // https://github.com/unbroken-dome/gradle-xjc-plugin
}

...

dependencies {
    xjcClasspath 'info.hubbitus:xjc-documentation-annotation-plugin:1.0'
}

// Results by default in `build/xjc/generated-sources`
xjcGenerate {
    source = fileTree('src/main/resources') { include '*.xsd' }
    packageLevelAnnotations = false
    targetPackage = 'info.hubbitus.xjc.plugin.example'
    extraArgs = [ '-XPluginDescriptionAnnotation' ]
}

Komplettes gradle Beispiel in Beispiel-Projekt -gradle Verzeichnis Projekt.