php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Request #58175 Add <documentation></documentation> to WSDL
Submitted: 2008-04-25 12:01 UTC Modified: 2017-01-10 08:11 UTC
From: silvano@php.net Assigned:
Status: Suspended Package: SCA_SDO (PECL)
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2008-04-25 12:01 UTC] silvano@php.net
Description:
------------
It would be useful to have an option to add the method's description in the doc blocks to the WSDL as <documentation></documentation>

Reproduce code:
---------------
/**
 * This is the description of my service
 * 
 * @service
 * @binding.soap
 */
class myService {
    
    /**
     * Description of my method
     * 
     * @param string $input Input description
     * @return string Output description
     */
    public function myMethod( $input ) {
        return $input;
    }
}

Expected result:
----------------
(...)
  <wsdl:portType name="myServicePortType">
    <wsdl:documentation>
      This is the description of my service
    </wsdl:documentation>

    <wsdl:operation name="myMethod">
      <wsdl:documentation>
        Description of my method
      </wsdl:documentation>
      <wsdl:input message="tns2:myMethodRequest"/>
      <wsdl:output message="tns2:myMethodResponse"/>
    </wsdl:operation>
  </wsdl:portType>
(...)

Actual result:
--------------
(...)
  <wsdl:portType name="myServicePortType">

    <wsdl:operation name="myMethod">
      <wsdl:input message="tns2:myMethodRequest"/>
      <wsdl:output message="tns2:myMethodResponse"/>
    </wsdl:operation>
  </wsdl:portType>
(...)

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2008-05-30 11:57 UTC] silvano@php.net
Here is a patch:
Note: I left the Service documentation out of this. This is ONLY for methods.


Index: Bindings/soap/ServiceDescriptionGenerator.php
===================================================================
RCS file: /repository/pecl/sdo/SCA/Bindings/soap/ServiceDescriptionGenerator.php,v
retrieving revision 1.6
diff -u -r1.6 ServiceDescriptionGenerator.php
--- Bindings/soap/ServiceDescriptionGenerator.php	3 Mar 2008 17:56:36 -0000	1.6
+++ Bindings/soap/ServiceDescriptionGenerator.php	30 May 2008 15:44:36 -0000
@@ -150,6 +150,15 @@
             foreach ($service_desc->operations as $op_name => $params) {
                 $portType_operation         = $portType->createDataObject('operation');
                 $portType_operation->name     = $op_name;
+
+                if ( sizeof($params['description']) > 0 ) {
+					$documentation     = $portType_operation->createDataObject('documentation');
+					$documentation_seq = $documentation->getSequence();
+                    foreach ( $params['description'] AS $description ) {
+                        $documentation_seq->insert($description['description'] . ' ');
+                    }
+                }
+                
                 $pt_input                     = $portType_operation->createDataObject('input');
                 $pt_input->message             = "{$wsdl->targetNamespace}#{$op_name}Request";
                 $pt_output                     = $portType_operation->createDataObject('output');
Index: SCA_AnnotationRules.php
===================================================================
RCS file: /repository/pecl/sdo/SCA/SCA_AnnotationRules.php,v
retrieving revision 1.5
diff -u -r1.5 SCA_AnnotationRules.php
--- SCA_AnnotationRules.php	4 May 2007 15:05:41 -0000	1.5
+++ SCA_AnnotationRules.php	30 May 2008 14:01:52 -0000
@@ -87,7 +87,7 @@
         public function isMethodAnnotation( $line )
         {
             return ( $this->isParameter($line) || $this->isReturn($line) ||
-                     $this->isName($line)) ? 
+                     $this->isName($line) || $this->isDescription($line) ) ? 
                 true : false ;
 
         }/* End is parameter function                                              */
@@ -123,7 +123,21 @@
         public function isName( $line )
         {
             return ( strpos($line, self::NAME) != false ) ? true : false ;
-        }/* End is name function                                                   */
+        }/* End is name function      
+
+        /**
+         * Is the description of the method
+         *
+         * @param string $line
+         * @return boolean
+         */
+        public function isDescription( $line )
+        {
+            return ( ( strpos($line, self::AT) !== 0 ) &&
+            ( strpos($line, self::FORESLASH . self::STAR . self::STAR) === false )
+            && ( strpos($line, self::STAR . self::FORESLASH) === false ) )
+            ? true : false ;
+        }/* End is description function                                                   */
 
         /**
          * Is the data type defined as an object.
Index: SCA_CommentReader.php
===================================================================
RCS file: /repository/pecl/sdo/SCA/SCA_CommentReader.php,v
retrieving revision 1.7
diff -u -r1.7 SCA_CommentReader.php
--- SCA_CommentReader.php	3 Mar 2008 17:56:36 -0000	1.7
+++ SCA_CommentReader.php	30 May 2008 15:19:52 -0000
@@ -46,6 +46,7 @@
         const   PARAM_ANNOTATION        = 'parameters' ;
         const   RETRN_ANNOTATION        = 'return' ;
         const   NAME_ANNOTATION         = 'name' ;
+        const   DESCR_ANNOTATION        = 'description' ;
 
         private $docComment             = null ;
         private $Rule                   = null ;
@@ -146,7 +147,7 @@
                         } else if ( strcmp($words[ 0 ], SCA_AnnotationRules::NAME) === 0 ) {
                             $this->methodAnnotations[ self::NAME_ANNOTATION ] =
                             $this->setMethodAlias($words);
-                        } else {
+                        } else if ( strcmp($words[ 0 ], SCA_AnnotationRules::RETRN) === 0 ) {
                             /* Ensure that no syntax error has been detected       */
                             if ( ($checkValue = $this->setReturnValues($words)) != null ) {
                                 $this->methodAnnotations[ self::RETRN_ANNOTATION ][ 0 ] =
@@ -155,7 +156,11 @@
                                 $reason = "Invalid return annotation syntax in '{$line}' " ;
                                 throw new SCA_RuntimeException($reason);
                             }/* End syntax check                                   */
-
+                        } else {
+                            if ( is_array($words) ) {
+                                $this->methodAnnotations[ self::DESCR_ANNOTATION ][] = 
+                                $this->setDescriptionValues($words);
+                            }
                         }/* End parameter or return annotations                    */
 
                     } else {
@@ -303,6 +308,22 @@
         }/* End set return annotation values function                               */
 
         /**
+        * Build an array containing the contents of description lines.
+        *
+        * @param  array   Containing the raaw words
+        * @return array   for the WSDL
+        */
+        public function setDescriptionValues( $words )
+        {
+            $returnValue                   = array() ;
+            $returnValue['annotationType'] = self::DESCR_ANNOTATION ;
+            $returnValue[ 'description' ]  = implode(" ", $words) ;
+
+            return  $returnValue ;
+
+        }/* End set description values function                                     */
+
+        /**
         * Return method alias specified using @name
         *
         * @param  array   Containing the raw words
 [2008-07-16 13:21 UTC] silvano@php.net
At SCA/Bindings/soap/ServiceDescriptionGenerator.php at line 154 it must be:

if ( isset($params['description']) ) {

instead of

if ( sizeof($params['description']) > 0 ) {

That generates a notice when there is no description for the method.
 [2017-01-10 08:11 UTC] kalle@php.net
-Status: Open +Status: Suspended
 [2017-01-10 08:11 UTC] kalle@php.net
Suspending this report as the extension have not had a release for almost 9 years.  Please revive this if the extension once again shows life
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sat Dec 21 11:01:30 2024 UTC