XFire
  1. XFire
  2. XFIRE-507

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. documented.wsdl
        7 kB
        Stefan Freyr Stefansson
      2. documented.wsdl
        6 kB
        Stefan Freyr Stefansson

        Activity

        Hide
        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
        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
        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
        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
        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
        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
          • Votes:
            2 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: