Come rendere le classi generate contengono Javadoc dalla documentazione dello schema XML

Question

Attualmente sto lavorando con uno schema XML che ha <xsd:annotation>/<xsd:documentation> sulla maggior parte dei tipi e degli elementi. Quando genero Java Beans da questo schema XML, il Javadoc di quei bean contiene solo alcune informazioni generiche generate sul contenuto consentito del tipo/elemento.

Mi piacerebbe vedere il contenuto del tag <xsd:documentation> nelle posizioni pertinenti (ad esempio il contenuto di tale tag per un complextType dovrebbe apparire nel Javadoc della classe generata per rappresentare quelTipo complesso).

Esiste un modo per raggiungere questo obiettivo?

Modifica: questo schema XML verrà utilizzato in un WSDL con JAX-WS, quindi questo tag potrebbe essere appropriato.

Edit 2: Ho letto su <jxb:javadoc>. Da quanto ho capito, posso specificarlo in un file di bind JAXB separato o direttamente nello schema XML. Questo avrebbe quasi risolto il mio problema. Ma preferirei usare il tag esistente <xsd:documentation>, dal momento che Javadoc non è l'obiettivo principale della documentazione (sono le informazioni sulla struttura dei dati principalmente e non sui Java Bean generati da esso) e per consentire agli strumenti non JAXB di accedere alle informazioni anche. Fornire la documentazione sia in <jxb:javadoc> che in xsd:documentation> "sembra" sbagliato, perché sto duplicando i dati (e lavoro) senza una buona ragione.

Edit 3: Grazie per la risposta di Pascal mi sono reso conto che ho già una mezza soluzione: Il <xsd:documentation> di complexType s viene scritto all'inizio della sua Javadoc! Il problema è comunque che solo viene utilizzato complexType s e simpleType s (che può anche risultare in una classe) e gli elementi sono ancora senza Javadoc.

Answer 1

Non sono mai stato in grado di ottenere regolare xsd:documentation da inserire nella sorgente java tranne se e solo se era un tipo complesso. La documentazione per gli elementi, i tipi semplici, ecc. Vengono ignorati.

Quindi, alla fine utilizzo jxb:javadoc. Per fare ciò, includere la definizione di xmlns:jxb="http://java.sun.com/xml/ns/jaxb" nell'elemento <xsd:schema>.

Aggiungi un bambino di <xsd:complexType> o <xsd: element> o <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> 

dove XXX è o "classe" o "proprietà".

Per un pacchetto si scrive un bambino di 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> 

documento

Writing HTML richiede bracketing con <![CDATA[ --- ]]>

(EDIT: Mentre scrivevo la mia risposta, la questione è stata curata dal PO così ho' m aggiornandolo di conseguenza)

Nel mio caso, javadoc era l'unico obiettivo quindi era accettabile usare jxb:javadoc. Ma il tuo aggiornamento ha perfettamente senso e, in realtà, sono totalmente d'accordo con te.Purtroppo, non ho mai trovato una soluzione ideale per la situazione che descrivi (quindi seguirò questa domanda molto attentamente). Forse potresti usare qualcosa come xframe per generare documentazione da xsd:documentation, ma questo non risponde alla domanda.

Answer 2

Questo non è possibile con l'implementazione di riferimento JAXB. Anche se dovessi provare a scrivere un plug-in XJC, scoprirai che all'API del plugin non viene fornito alcun riferimento alla definizione dello schema, quindi non c'è modo di estrarre queste informazioni.

La nostra unica speranza è che una versione futura di JAXB risolva la situazione. C'è un open feature request here.

Answer 3

Trovo che le seguenti tecniche funzionino piuttosto bene per aggiungere intestazioni JavaDoc alle classi di elementi Java (generate da schemi XML). Annido JavaDoc nei tag definiti nello spazio dei nomi jax-b, nidificati all'interno dell'annotazione dello schema xml e dei tag appinfo. Nota lo spazio dei nomi jaxb definisce i tipi di tag di documentazione; Ne uso due: la classe e i tag di proprietà. definito nel seguente spazio dei nomi: xmlns: jxb = "http://java.sun.com/xml/ns/jaxb"

1) Per documentare una classe, utilizzo un tag "classe" jaxb nella seguente sequenza :

<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) per documentare un elemento, io uso il tag "proprietà" come segue:

 <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) io uso lo stesso set di tag per documentare gli attributi:

 <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) Per documentare una scelta, utilizzo la proprietà jaxb tag e documento la scelta.

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

Il tentativo di documentare le scelte individuali qui fallirebbe, dal momento che questo tag produce un elenco non tipizzato.