CXF wsdl2java not generating Javadoc for members

Question

Running wsdl2java from CXF 2.7.5 for something like

<xsd:complexType name="baseTaxParametersEnhanced">
  <xsd:annotation>
    <xsd:documentation>
      Some type comment.
    </xsd:documentation>
  </xsd:annotation>
  <xsd:sequence>
    <xsd:element name="municipality" type="xsd:string">
      <xsd:annotation>
        <xsd:documentation>
          Some member comment.
        </xsd:documentation>
      </xsd:annotation>
    </xsd:element>
    <xsd:element name="zip" type="xsd:string" />

produces Javadoc for the BaseTaxParametersEnhanced class but not for the municipality member.

This comes unexpected and I didn't see a flag mentioned in the docs to turn this on/off?

Answer 1

Unfortunately there is little that can be done to easily fix it. wsdl2java uses xjc under the hood to generate classes. There is an old issue raised for that (JAXB-172). You can vote for it. There is no xjc plugin that fixes that. More on this issue was mentioned in How to make generated classes contain Javadoc from XML Schema documentation.

As it is described there if you have control over WSDL/XSD files you can replace xsd:documentation with embedded custom binding (jxb:javadoc). To achieve that you should declare jxb namespace, something like:

<xsd:schema ... xmlns:jxb="http://java.sun.com/xml/ns/jaxb">

and change your type declaration:

<xsd:complexType name="baseTaxParametersEnhanced">
    <xsd:annotation>
        <xsd:appinfo>
            <jxb:class>
                <jxb:javadoc>Some type comment.</jxb:javadoc>
            </jxb:class>
        </xsd:appinfo>
    </xsd:annotation>
    <xsd:sequence>
        <xsd:element name="municipality" type="xsd:string">
            <xsd:annotation>
                <xsd:appinfo>
                    <jxb:property>
                        <jxb:javadoc>Some member comment.</jxb:javadoc>
                    </jxb:property>
                </xsd:appinfo>
            </xsd:annotation>
        </xsd:element>
        <xsd:element name="zip" type="xsd:string" />
    </xsd:sequence>
</xsd:complexType>

The problem with this solution is that those comments won't be recognized by other WSDL/XSD tools.

If you have no control over WSDL/XSD you can do the same using external JAXB bindings, but it seems too much overhead.

Summarizing please upvote mentioned issue if you can. Maybe one day someone decides that it's high time to implement the feature.

EDIT

As I considered it weird that one cannot use XJC plugin to perform such a task (one of the comments from mentioned question stated that) I decided to try to write such a plugin.

The result can be found here: https://github.com/destin/xjc-javadoc-plugin

Currently it adds comments only to fields (not getters or setters) of complex types. I would be really grateful for any suggestions for improvement. When I consider it stable enough I'll try to contribute it to CXF project so that anyone can easily use it.