XFire

Documentation support for WSDL->Java and Java->WSDL

Details

  • Type: Improvement Improvement
  • Status: Resolved Resolved
  • Priority: Minor Minor
  • Resolution: Fixed
  • Affects Version/s: 1.1.2
  • Fix Version/s: 1.2.3
  • Component/s: Generator
  • Labels:
    None
  • Number of attachments :
    2

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).

  1. XML File
    documented.wsdl
    29/Jun/06 12:43 PM
    7 kB
    Stefan Freyr Stefansson
  2. XML File
    documented.wsdl
    29/Jun/06 12:40 PM
    6 kB
    Stefan Freyr Stefansson

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Stefan Freyr Stefansson added a comment -

Updated version including more examples of documentation... please use this file and discard the previous one.

Show
Stefan Freyr Stefansson added a comment - Updated version including more examples of documentation... please use this file and discard the previous one.
Hide
Permalink
Michael Vorburger added a comment -

The <wsdl:documentation> is only of interest to document operations and a complete service, for the messages/types it is not all that interesting IMHO. It's probably not very hard to get that out of JSR110/wsdl4j when generating the service interface (not *Impl!) class. Tomasz?

Getting the <xsd:annotation><xsd:documentation> into the generated Bean would sure be helpful... and something many JAX-RPC Implementations, including Axis 1.x, do! Only that of course, that is not an XFire but a JAXB issue... which is why I raised https://jaxb.dev.java.net/issues/show_bug.cgi?id=172 a while ago! Whenever jaxb Issue 172 gets addressed (they don't seem to be in a hurry, unfortunately), XFire should upgrade to the next official JAXB drop to benefit from this.

Show
Michael Vorburger added a comment - The <wsdl:documentation> is only of interest to document operations and a complete service, for the messages/types it is not all that interesting IMHO. It's probably not very hard to get that out of JSR110/wsdl4j when generating the service interface (not *Impl!) class. Tomasz? Getting the <xsd:annotation><xsd:documentation> into the generated Bean would sure be helpful... and something many JAX-RPC Implementations, including Axis 1.x, do! Only that of course, that is not an XFire but a JAXB issue... which is why I raised https://jaxb.dev.java.net/issues/show_bug.cgi?id=172 a while ago! Whenever jaxb Issue 172 gets addressed (they don't seem to be in a hurry, unfortunately), XFire should upgrade to the next official JAXB drop to benefit from this.
Hide
Permalink
Stefan Freyr Stefansson added a comment -

Everyone interested in seeing this feature, please go to https://jaxb.dev.java.net/issues/show_bug.cgi?id=172 log in and vote for that issue.

Show
Stefan Freyr Stefansson added a comment - Everyone interested in seeing this feature, please go to https://jaxb.dev.java.net/issues/show_bug.cgi?id=172 log in and vote for that issue.
Hide
Permalink
Tomasz Sztelak added a comment -

Ok, Just commited some initial work for wsdl:documentation support ( java->wsdl for now ).
Cofiguration of this feature is similar to aegis mapping files, you must place file MyService.doc.xml in folder where MyService.class is located. Config file has following syntax :

<service>
<documentation>
DOCUMENTATION FOR SERVICE
</documentation>
<method name="METHOD_NAME" parametersNumber="NUMBER_OF_METHOD_ARGUMENTS" >
<documentation>
METHOD DOCUMENTATION
</documentation>
<parameter index="0">
<documentation>
DOCUMENTATION FOR FIRST PARAM
</documentation>
</parameter>
</method>
</service>

Practical sample can be seen in distribution book example.

Show
Tomasz Sztelak added a comment - Ok, Just commited some initial work for wsdl:documentation support ( java->wsdl for now ). Cofiguration of this feature is similar to aegis mapping files, you must place file MyService.doc.xml in folder where MyService.class is located. Config file has following syntax : <service> <documentation> DOCUMENTATION FOR SERVICE </documentation> <method name="METHOD_NAME" parametersNumber="NUMBER_OF_METHOD_ARGUMENTS" > <documentation> METHOD DOCUMENTATION </documentation> <parameter index="0"> <documentation> DOCUMENTATION FOR FIRST PARAM </documentation> </parameter> </method> </service> Practical sample can be seen in distribution book example.
Hide
Permalink
Tomasz Sztelak added a comment -

java -> wsdl documentation generation works for : service comments, methods, method's params , results and exceptions.

For wsdl-> java the new issue is opened : http://jira.codehaus.org/browse/XFIRE-776

Show
Tomasz Sztelak added a comment - java -> wsdl documentation generation works for : service comments, methods, method's params , results and exceptions. For wsdl-> java the new issue is opened : http://jira.codehaus.org/browse/XFIRE-776
Hide
Permalink
QinJia added a comment - - edited

I use this method to create a MyService.doc.xml.Here is my configuration.
<service>
<documentation>this is a description of 1</documentation>
<method name="example" parametersNumber="1" >
<documentation>this is a description of 2</documentation>
<parameter index="0">
<documentation>this is a description</documentation>
</parameter>
</method>
</service>
The project has no problem,but the generated wsdl has some problems.
I can only see "<xsd:documentation>this is a description</xsd:documentation>
" in the wsdl,but the other two documentation description is missing.
what's the problem?could you tell me ?thanks a lot

Show
QinJia added a comment - - edited I use this method to create a MyService.doc.xml.Here is my configuration. <service> <documentation>this is a description of 1</documentation> <method name="example" parametersNumber="1" > <documentation>this is a description of 2</documentation> <parameter index="0"> <documentation>this is a description</documentation> </parameter> </method> </service> The project has no problem,but the generated wsdl has some problems. I can only see "<xsd:documentation>this is a description</xsd:documentation> " in the wsdl,but the other two documentation description is missing. what's the problem?could you tell me ?thanks a lot

People

  • Assignee:
    Tomasz Sztelak
    Reporter:
    Stefan Freyr Stefansson
Vote (2)
Watch (5)

Dates

  • Created:
    Updated:
    Resolved: