7

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?

Marcel Stör
  • 22,695
  • 19
  • 92
  • 198

2 Answers2

10

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.

Community
  • 1
  • 1
Dawid Pytel
  • 2,750
  • 1
  • 23
  • 30
  • Wonderful! Wish I could do more than accept & upvote. Thanks a bunch. – Marcel Stör Oct 20 '13 at 22:11
  • 1
    Nice!! Thank you very much. (I'm the original reporter of JAXB-172, 7.5 years ago!) – vorburger Oct 21 '13 at 00:46
  • @MarcelStör thanks, you can ask friends to upvote JAXB-172 ;) – Dawid Pytel Oct 21 '13 at 06:35
  • 1
    @vorburger Whoa! 7.5 years in IT is like a century! It's even more strange if you consider the fact that everything is in place to implement it (as my plugin shows). I'll try to analyse XJC code and check whether more Javadoc can be easily added. If it is the case then I'll provide a patch to JAXB. Hopefully the problem will finally get solved. – Dawid Pytel Oct 21 '13 at 06:36
  • @DawidPytel "you can ask friends to upvote JAXB-172" - I'll certainly do that. However, given how long the bug/feature request has been around I doubt this impresses anyone. – Marcel Stör Oct 21 '13 at 06:54
0

About xjc-javadoc-plugin. As written on project page: "Plugin has been incorporated into Apache CXF XJC Utils". Although on page https://cxf.apache.org/xjc-utils.html has nothing about it. But it there and works as "adds javadocs based on xsd:documentation element". For using plugin "from Apache":

<plugin>
  <groupId>org.apache.cxf</groupId>
  <artifactId>cxf-codegen-plugin</artifactId>
  <version>3.3.5</version>
  <executions>
    <execution>
      <!-- ... -->
      <configuration>
        <wsdlOptions>
          <wsdlOption>
            <!-- ... -->
            <extraargs>
              <extraarg>-xjc-Xjavadoc</extraarg>
            </extraargs> 
          </wsdlOption>
        </wsdlOptions>
      </configuration>
    </execution>
  </executions>
  <dependencies>
    <dependency>
      <groupId>org.apache.cxf.xjcplugins</groupId>
      <artifactId>cxf-xjc-javadoc</artifactId>
      <version>3.3.1</version>
    </dependency>
  </dependencies>
</plugin>

or

<plugin>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-xjc-plugin</artifactId>
    <version>3.3.1</version>
    <configuration>
        <extensions>
            <extension>org.apache.cxf.xjcplugins:cxf-xjc-javadoc:3.3.1</extension>
        </extensions>
    </configuration>
    <executions>
        <execution>
            <!-- ... -->
            <configuration>
                <!-- ... -->
                <xsdOptions>
                    <xsdOption>
                        <!-- ... -->
                        <extensionArgs>-Xjavadoc</extensionArgs>
                    </xsdOption>
                </xsdOptions>
            </configuration>
        </execution>
    </executions>
</plugin>
terran
  • 1
  • 2