3

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?

Community
  • 1
  • 1
inanutshellus
  • 9,683
  • 9
  • 53
  • 71

1 Answers1

0

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

artbristol
  • 32,010
  • 5
  • 70
  • 103