How to make generated classes contain Javadoc from XML Schema documentation

Question

I'm currently working with an XML Schema that has <xsd:annotation>/<xsd:documentation> on most types and elements. When I generate Java Beans from this XML Schema, then the Javadoc of those Beans only contains some generic generated information about the allowed content of the type/element.

I'd like to see the content of the <xsd:documentation> tag in the relevant places (for example the content of that tag for a complextType should show up in the Javadoc of the class generated to represent that complexType).

Is there any way to achieve this?

Edit: this XML Schema will be used in a WSDL with JAX-WS, so this tag might be appropriate as well.

Edit 2: I've read about <jxb:javadoc>. From what I understand I can specify that either in a separate JAXB binding file or directly in the XML Schema. That would almost solve my problem. But I'd rather use the existing <xsd:documentation> tag, since Javadoc is not the primary target of the documentation (it's information about the data structure primarily and not about the Java Beans generated from it) and to allow non-JAXB tools to access the information as well. Providing the documentation in both <jxb:javadoc> and xsd:documentation> "feels" wrong, because I'm duplicating data (and work) for no good reason.

Edit 3: Thanks to the answer by Pascal I realized that I already have half a solution: The <xsd:documentation> of complexTypes is written to the beginning of its Javadoc! The problem is still that only that complexTypes is used and simpleTypes (which can also result in a class) and elements are still Javadoc-less.

Answer 1

I've never been able to get regular xsd:documentation to be placed in the java source except if and only if it was a Complex Type. Documentation for elements, simple types, etc are ignored.

So, I end up using jxb:javadoc. To do so, include the definition of xmlns:jxb="http://java.sun.com/xml/ns/jaxb" in your <xsd:schema> element.

Add a child to <xsd:complexType> or <xsd: element> or <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>

Where XXX is either "class" or "property".

For a package you write a child to 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>

Writing HTML document requires bracketing with <![CDATA[ --- ]]>

(EDIT: While writing my answer, the question has been edited by the OP so I'm updating it accordingly)

In my case, javadoc was the only target so it was acceptable to use jxb:javadoc. But your update makes perfect sense and, actually, I totally agree with you. Sadly, I never found an ideal solution for the situation you describe (so I'll follow this question very carefully). Maybe you could use something like xframe to generate documentation from xsd:documentation, but this doesn't answer the question.

Answer 2

This just isn't possible with the JAXB reference implementation. Even if you were to try to write an XJC plugin, you'd find that the plugin API is given no reference to the Schema definition, so there's no way to extract this information.

Our only hope is that a future version of JAXB fixes the situation. There's an open feature request here.