Details
Description
It would be good if the XFire "generator" could provide a way to maintain any documentation that is done in either WSDL or Java classes.
This documentation would probably have to be maintained using annotations. The reason for this being that retrieveing the JavaDoc from a class file is (to my knowledge) not possible and therefore, the JavaDoc cannot be transported over to the generated WSDL. However it would of course be possible to generate java classes with javadoc from porperly constructed WSDL but that would just work in that direction.
There seem to be different ways to document things in a WSDL file. http://www.w3.org/TR/wsdl#_document-s provides a good overview of where an <wsdl:documentation> element can be placed but it seems that within the type definitions (in the namespace for XSD) there seems to be a tendency to use <xsd:annotation><xsd:documentation>...</xsd:documentation></xsd:annotation>. Whether there are other ways of doing this I don't know.
I'm supplying a WSDL file with examples of both the wsdl: and xsd: documentations. Please note that I have not tested this WSDL file but I'm fairly confident that it should be legal. Also please note that this WSDL does not provide an exhaustive test case... that is some items that can be documented in the WSDL are not in the file provided (such as the wsdl:message element, the wsdl:binding or any sub-element of that or the wsdl:service or any sub-element of that).
Updated version including more examples of documentation... please use this file and discard the previous one.