Question

I’ve developed a webservice and rightfully my users would like to see documentation. I’d prefer to simply document my code, either with javadoc comments or with an explicit annotation, e.g.

@XmlComment("This is used to [blah blah]")
@XmlElement(name = "referenceDate", namespace = NAMESPACE, type = Date.class)
public void setReferenceDate(Date referenceDate) {
    this.referenceDate = referenceDate;
}

or

/**
 * This is used to [blah blah]
 */
@XmlElement(name = "referenceDate", namespace = NAMESPACE, type = Date.class)
public void setReferenceDate(Date referenceDate) {
    this.referenceDate = referenceDate;
}

The above aren’t supported, as evidenced here:

• JAXB-273 – 2006 request to make xs:documentation elements from annotations
• JAXB-369 – 2007 request to make xs:documentation elements from comments
• SO-470001 – “You can’t do that” stackoverflow question

So I understand I can’t use the above to I comment my service. But… Surely there’s still a way to do so in a non-manual fashion. Must I hand-craft all my XML just for this? If that is the answer, why isn’t there more attention on getting this feature into JAXB? Seems downright mandatory for an enterprise-grade webservice, right?

Answer 1

You’re right it’s poor. Most focus these days is on contract-first, so I guess it’s not been prioritized. You could use XSLT to add in the comments to the WSDL from a separate XML doc. Not as good as generating it from the Java code, but better than nothing. Here’s an ancient posting doing it http://www.gridlab.org/WorkPackages/wp-5/guide/wsdltips.html