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

javadoc eclipse

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 <xsd:documentation> en los lugares relevantes (por ejemplo, el contenido de esa etiqueta para un complextType debe aparecer en el Javadoc de la clase generada para representar ese complexType).

¿Hay alguna forma de lograr esto?

Editar : este esquema XML se usará 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 <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 herramientas que no sean de JAXB. para acceder 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.

Edición 3 : Gracias a la respuesta de Pascal, me di cuenta de que ya tenía media solución: ¡La <xsd:documentation> de complexType s está escrita al comienzo de su Javadoc! El problema sigue siendo que solo se utiliza ese tipo complexType y simpleType (que también pueden dar como resultado una clase) y los elementos aún no tienen Javadoc.

Answer 1

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 nombre: 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) Para 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) Utilizo el mismo conjunto de etiquetas para documentar los 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>

Intentar documentar las elecciones individuales aquí fallaría, ya que esta etiqueta produce una lista sin tipo.

Answer 2

Esto simplemente no es posible con la implementación de referencia 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 una solicitud de función abierta aquí .

Answer 3

Nunca pude obtener xsd:documentation regular para xsd:documentation en el origen de Java, excepto si solo era un Tipo complejo. La documentación de elementos, tipos simples, etc. se ignora.

Entonces, 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> .

Agregue un elemento secundario 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 "clase" o "propiedad".

Para un paquete, escriba un hijo en 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>

Escribir un documento HTML requiere el horquillado con <![CDATA[ --- ]]>

(EDITAR: Mientras escribo mi respuesta, la OP ha editado la pregunta, así que la actualizo 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ías usar algo como xframe para generar documentación de xsd:documentation , pero esto no responde la pregunta.