Cómo hacer que las clases generadas contengan Javadoc desde la documentación del esquema XML

Question

Actualmente estoy trabajando con un esquema XML que tiene <xsd:annotation>/<xsd:documentation> en la mayoría de los tipos y elementos. Cuando genero Java Beans a partir de este Esquema XML, el Javadoc de esos Beans solo contiene información genérica generada sobre el contenido permitido del tipo/elemento.

Me gustaría ver el contenido de la etiqueta <xsd:documentation> en los lugares relevantes (por ejemplo, el contenido de esa etiqueta para un tipo complext debería aparecer en el Javadoc de la clase generada para representar ese complexType).

¿Hay alguna manera de lograr esto?

Editar: este esquema XML se utilizará en un WSDL con JAX-WS, por lo que esta etiqueta también podría ser adecuada.

Editar 2: He leído sobre <jxb:javadoc>. Por lo que entiendo, puedo especificar eso en un archivo de enlace JAXB separado o directamente en el esquema XML. Eso casi solucionaría mi problema. Pero preferiría usar la etiqueta existente <xsd:documentation>, ya que Javadoc no es el objetivo principal de la documentación (es información sobre la estructura de datos principalmente y no sobre los beans de Java generados a partir de ella) y permitir que herramientas que no sean de JAXB accedan a la información también. Proporcionar la documentación en <jxb:javadoc> y xsd:documentation> "se siente" mal, porque estoy duplicando datos (y trabajo) sin una buena razón.

Datos 3: Gracias a la respuesta de Pascal me di cuenta de que ya tengo la mitad de una solución: La <xsd:documentation> de complexType s se escribe en el comienzo de su Javadoc! El problema es que solo que se usa complexType s y simpleType s (que también pueden dar como resultado una clase) y los elementos aún no tienen Javadoc.

Answer 1

Nunca he podido obtener xsd:documentation normal para ser colocado en la fuente java excepto si y solo si era un tipo complejo. La documentación para elementos, tipos simples, , etc. se ignoran.

Por lo tanto, termino usando jxb:javadoc. Para hacerlo, incluya la definición de xmlns:jxb="http://java.sun.com/xml/ns/jaxb" en su elemento <xsd:schema>.

Añadir un niño a <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> 

donde XXX es o "clase" o "propiedad".

Para un paquete se escribe un niño a 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

escritura HTML requiere horquillado con <![CDATA[ --- ]]>

(EDIT: Al escribir mi respuesta, la pregunta ha sido editada por la OP por lo que' m actualizándolo en consecuencia)

En mi caso, javadoc era el único objetivo, por lo que era aceptable usar jxb:javadoc. Pero su actualización tiene mucho sentido y, de hecho, estoy totalmente de acuerdo con usted.Tristemente, nunca encontré una solución ideal para la situación que describes (así que seguiré esta pregunta con mucho cuidado). Tal vez podría usar algo como xframe para generar documentación desde xsd:documentation, pero esto no responde la pregunta.

Answer 2

Esto simplemente no es posible con la implementación de referencia de JAXB. Incluso si intentara escribir un plugin XJC, encontraría que a la API del complemento no se le da ninguna referencia a la definición del esquema, por lo que no hay forma de extraer esta información.

Nuestra única esperanza es que una versión futura de JAXB corrija la situación. Hay un open feature request here.

Answer 3

Encuentro que las siguientes técnicas funcionan bastante bien para agregar encabezados de JavaDoc a las clases de elementos de Java (generadas a partir de esquemas XML). Anido el JavaDoc en las etiquetas definidas en el espacio de nombres jax-b, anidado dentro de las etiquetas de anotación de esquema xml y de info-app. Tenga en cuenta que el espacio de nombres jaxb define los tipos de etiquetas de documentación; Uso dos de allí: la clase y las etiquetas de propiedad. definido en el siguiente espacio de nombres: xmlns: jxb = "http://java.sun.com/xml/ns/jaxb"

1) Para documentar una clase, utilizo una etiqueta jaxb "clase" en la siguiente secuencia :

<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) documentar un elemento, utilizo la etiqueta "propiedad" de la siguiente manera:

 <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) que utilizan el mismo conjunto de etiquetas para documentar atributos:

 <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) Para documentar una elección, utilizo la propiedad jaxb tag, y documentamos la elección.

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

El intento de documentar las decisiones individuales que aquí sería un fracaso, ya que esta etiqueta produce una lista sin tipo.