jax-ws
  1. jax-ws
  2. JAX_WS-952

Added Javadoc implementation for methods parameters, returns and throws

    Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Minor Minor
    • Resolution: Unresolved
    • Affects Version/s: 2.2, 2.2.1, 2.2.2, 2.2.3, 2.2.4, current
    • Fix Version/s: None
    • Component/s: wsimport
    • Labels:
      None
    • Environment:

      Windows XP, Java 5 with JAXB 2.2.X

      Description

      Hello.

      I added documentation handling for the parameters, returns and throws of the webmethods generated via wsimport/wscompile.

      Ex consider this WSDL :
      ...
      <message name="getContent">
      <part name="password" element="ns6:mdp" xmlns:ns6="urn:client.ws.example.gouv.fr">
      <documentation>The password.</documentation>
      </part>
      <part name="idContent" element="tns:idContent">
      <documentation>The content ID.</documentation>
      </part>
      </message>
      <message name="getContentResponse">
      <part name="content" element="tns:content">
      <documentation>The content you requested.</documentation>
      </part>
      </message>
      <message name="WSTechnicalException">
      <part name="fault" element="ns3:WSTechnicalExceptionBean" xmlns:ns3="urn:exceptions.client.ws.example.gouv.fr">
      <documentation>An exception providing the technical fault that occured.</documentation>
      </part>
      </message>
      <message name="WSBusinessException">
      <part name="fault" element="ns4:WSBusinessExceptionBean" xmlns:ns4="urn:exceptions.client.ws.example.gouv.fr">
      <documentation>An exception providing the business faults that occured.</documentation>
      </part>
      </message>
      ...
      <operation name="getContent" parameterOrder="mdp idContent">
      <documentation>This method give you the content you desire.</documentation>
      <input wsam:Action="urn:client.ws.example.gouv.fr:ExampleWS:getContentRequest" message="tns:getContent"/>
      <output wsam:Action="urn:client.ws.example.gouv.fr:ExampleWS:getContentResponse" message="tns:getContentResponse"/>
      <fault message="tns:WSTechnicalException" name="WSTechnicalException" wsam:Action="urn:client.ws.example.gouv.fr:ExampleWS:getContent:Fault:WSTechnicalException">
      <documentation>Exception that wrap the technical exceptions sent by the WS.</documentation>
      </fault>
      <fault message="tns:WSBusinessException" name="WSBusinessException" wsam:Action="urn:client.ws.example.gouv.fr:ExampleWS:getContent:Fault:WSBusinessException">
      <documentation>Exception that wrap the business exceptions sent by the WS.</documentation>
      </fault>
      </operation>
      ......

      The generated method will be :

      /**

      • This method give you the content you desire.
      • @param password
      • The password.
      • @param idContent
      • The content ID.
      • @return
      • The content you requested.
      • @throws WSBusinessException
      • An exception providing the technical fault that occured.
      • @throws WSTechnicalException
      • An exception providing the business faults that occured.
        */
        @WebMethod
        @WebResult(name = "content", targetNamespace = "urn:client.ws.example.gouv.fr", partName = "content")
        public void getContent(
        @WebParam(name = "password", targetNamespace = "urn:client.ws.example.gouv.fr", header = true, partName = "password")
        String password,
        @WebParam(name = "idContent", targetNamespace = "urn:client.ws.example.gouv.fr", partName = "idContent")
        String idContent )
        throws WSBusinessException, WSTechnicalException
        ;

      This would work with every 2.2.x versions of JAX-WS.

      The patch is provided in attachment.

      Cheers !

        Activity

        Hide
        mauromol added a comment -

        Having the WSDL documentation for parameters copied on the generated interface methods parameter Javadoc would be VERY useful. Why this patch has not been applied yet?

        Show
        mauromol added a comment - Having the WSDL documentation for parameters copied on the generated interface methods parameter Javadoc would be VERY useful. Why this patch has not been applied yet?
        Hide
        diversit added a comment -

        Please apply this patch asap. Since Java 8 is much more strict on the Javadoc, this patch is really needed to immensely reduce the number of javadoc error/warnings.

        Show
        diversit added a comment - Please apply this patch asap. Since Java 8 is much more strict on the Javadoc, this patch is really needed to immensely reduce the number of javadoc error/warnings.
        Hide
        Martin Grebac added a comment -

        Hi, when we are at it, would it be possible to also write a test for this?

        Show
        Martin Grebac added a comment - Hi, when we are at it, would it be possible to also write a test for this?

          People

          • Assignee:
            Unassigned
            Reporter:
            LusuM
          • Votes:
            2 Vote for this issue
            Watchers:
            5 Start watching this issue

            Dates

            • Created:
              Updated:

              Time Tracking

              Estimated:
              Original Estimate - 5 minutes
              5m
              Remaining:
              Remaining Estimate - 5 minutes
              5m
              Logged:
              Time Spent - Not Specified
              Not Specified