Jak wygenerować wygenerowane klasy zawierają Javadoc z dokumentacji schematu XML

Question

Obecnie pracuję ze schematem XML, który ma <xsd:annotation>/<xsd:documentation> dla większości typów i elementów. Kiedy generuję Java Beans z tego schematu XML, to Javadoc tych fasoli zawiera tylko generyczne generowane informacje o dozwolonej zawartości typu/elementu.

Chciałbym zobaczyć zawartość tagu <xsd:documentation> w odpowiednich miejscach (na przykład treść tego tagu dla complexTType powinna pojawić się w Javadoc klasy wygenerowanej do reprezentowania tego complexType).

Czy jest jakiś sposób, aby to osiągnąć?

Edycja: ten schemat XML będzie używany w pliku WSDL z JAX-WS, więc ten znacznik również może być odpowiedni.

Edytuj 2: Przeczytałem o <jxb:javadoc>. Z tego co rozumiem, mogę to określić w oddzielnym pliku powiązania JAXB lub bezpośrednio w schemacie XML. To prawie rozwiązałoby mój problem. Ale wolałbym używać istniejącego tagu <xsd:documentation>, ponieważ Javadoc nie jest głównym celem dokumentacji (chodzi przede wszystkim o strukturę danych, a nie o wygenerowaną z niego Java Beans) i pozwala narzędziom innym niż JAXB uzyskać dostęp do informacji także. Dostarczenie dokumentacji zarówno w <jxb:javadoc> jak i xsd:documentation> "źle się czuje", ponieważ duplikuję dane (i pracuję) bez żadnego powodu.

Edycja 3: Dzięki odpowiedź Pascal zdałem sobie sprawę, że mam już pół Rozwiązanie: <xsd:documentation> z complexType s jest napisane na początku swojej Javadoc! Problem nadal jest taki, że są używane i są używane, a elementy są nadal pozbawione Javadoc.

Answer 1

Nigdy nie byłem w stanie uzyskać regularnego xsd:documentation do umieszczenia w źródle java za wyjątkiem tylko wtedy, gdy był to typ złożony. Dokumentacja dla elementów, typy proste, itd. Są ignorowane.

Tak więc kończę używać jxb:javadoc. Aby to zrobić, dołącz definicję elementu xmlns:jxb="http://java.sun.com/xml/ns/jaxb" do elementu <xsd:schema>.

Dodać dziecku <xsd:complexType> lub <xsd: element> lub <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> 

gdzie XXX jest albo "klasa" czy "własność".

Dla pakietu piszesz dziecku 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> 

dokument

Pisanie HTML wymaga bracketing z <![CDATA[ --- ]]>

(EDIT: Pisząc moją odpowiedź na pytanie została edytowana przez OP więc” m aktualizuje to odpowiednio)

W moim przypadku javadoc był jedynym celem, więc można było używać jxb:javadoc. Ale twoja aktualizacja ma sens i, faktycznie, całkowicie się z tobą zgadzam.Niestety, nigdy nie znalazłem idealnego rozwiązania dla opisywanej sytuacji (dlatego bardzo uważnie podchodzę do tego pytania). Może mógłbyś użyć czegoś takiego jak xframe do wygenerowania dokumentacji od xsd:documentation, ale to nie odpowiada na pytanie.

Answer 2

Po prostu nie jest to możliwe z implementacją referencyjną JAXB. Nawet gdybyś spróbował napisać wtyczkę XJC, okazałoby się, że API wtyczki nie ma odniesienia do definicji schematu, więc nie ma sposobu na wyodrębnienie tych informacji.

Naszą jedyną nadzieją jest to, że przyszłą wersję JAXB naprawi sytuację. Jest open feature request here.

Answer 3

Następujące techniki działają całkiem nieźle, dodając nagłówki JavaDoc do klas elementów Java (generowanych ze schematów XML). Zagnieżdżam JavaDoc w znacznikach zdefiniowanych w przestrzeni nazw jax-b, zagnieżdżonych wewnątrz adnotacji schematu XML i znaczników appinfo. Uwaga: Przestrzeń nazw jaxb definiuje typy znaczników dokumentacji; Używam dwóch z nich: znaczników klasy i własności. zdefiniowane w następującej przestrzeni nazw: xmlns: jxb = "http://java.sun.com/xml/ns/jaxb"

1) Do udokumentowania klasy używam znacznika "klasa" jaxb w następującej sekwencji :

<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) w celu udokumentowania element używam "własność" tag następująco:

 <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) korzystać z tego samego zestawu tagów udokumentować atrybuty:

 <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) Aby udokumentować wybór, używam znacznika jaxb właściwości i dokumentuję wybór.

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

Próba udokumentować indywidualnych wyborów tu nie powiedzie, ponieważ tego tagu produkuje listę bez typu.