From 12acbc2678073c3439b427be0b713b97e2074bfb Mon Sep 17 00:00:00 2001 From: Brent Shaffer Date: Tue, 27 Jun 2017 16:28:28 -0700 Subject: adds PHPDoc @return and @param for getters and setters respectively (#3131) * adds PHPDoc @return and @param for getters and setters respectively * addresses changes in PR review * adds documentation tests * Update php_generator: - Prepend \ to names where required - Remove 
 tags
- Update protobuf field comments

* Updates class files with the protobuf changes

* Addresses review comments

* removes Protobuf Type line from PHP generated classes

* fixes phpdoc test

* adds array types to phpdoc
---
 .../Protobuf/Internal/FieldDescriptorProto.php     | 136 ++++++++++-----------
 1 file changed, 64 insertions(+), 72 deletions(-)

(limited to 'php/src/Google/Protobuf/Internal/FieldDescriptorProto.php')

diff --git a/php/src/Google/Protobuf/Internal/FieldDescriptorProto.php b/php/src/Google/Protobuf/Internal/FieldDescriptorProto.php
index 2af9c0a0..ae61be47 100644
--- a/php/src/Google/Protobuf/Internal/FieldDescriptorProto.php
+++ b/php/src/Google/Protobuf/Internal/FieldDescriptorProto.php
@@ -12,99 +12,85 @@ use Google\Protobuf\Internal\InputStream;
 use Google\Protobuf\Internal\GPBUtil;
 
 /**
- * 
  * Describes a field within a message.
- * 

  *
- * Protobuf type google.protobuf.FieldDescriptorProto
+ * Generated from protobuf message google.protobuf.FieldDescriptorProto
  */
 class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
 {
     /**
-     * optional string name = 1;
+     * Generated from protobuf field optional string name = 1;
      */
     private $name = '';
     private $has_name = false;
     /**
-     * optional int32 number = 3;
+     * Generated from protobuf field optional int32 number = 3;
      */
     private $number = 0;
     private $has_number = false;
     /**
-     * optional .google.protobuf.FieldDescriptorProto.Label label = 4;
+     * Generated from protobuf field optional .google.protobuf.FieldDescriptorProto.Label label = 4;
      */
     private $label = 0;
     private $has_label = false;
     /**
-     * 
      * If type_name is set, this need not be set.  If both this and type_name
      * are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP.
-     * 

      *
-     * optional .google.protobuf.FieldDescriptorProto.Type type = 5;
+     * Generated from protobuf field optional .google.protobuf.FieldDescriptorProto.Type type = 5;
      */
     private $type = 0;
     private $has_type = false;
     /**
-     * 
      * For message and enum types, this is the name of the type.  If the name
      * starts with a '.', it is fully-qualified.  Otherwise, C++-like scoping
      * rules are used to find the type (i.e. first the nested types within this
      * message are searched, then within the parent, on up to the root
      * namespace).
-     * 

      *
-     * optional string type_name = 6;
+     * Generated from protobuf field optional string type_name = 6;
      */
     private $type_name = '';
     private $has_type_name = false;
     /**
-     * 
      * For extensions, this is the name of the type being extended.  It is
      * resolved in the same manner as type_name.
-     * 

      *
-     * optional string extendee = 2;
+     * Generated from protobuf field optional string extendee = 2;
      */
     private $extendee = '';
     private $has_extendee = false;
     /**
-     * 
      * For numeric types, contains the original text representation of the value.
      * For booleans, "true" or "false".
      * For strings, contains the default text contents (not escaped in any way).
-     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
+     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
      * TODO(kenton):  Base-64 encode?
-     * 

      *
-     * optional string default_value = 7;
+     * Generated from protobuf field optional string default_value = 7;
      */
     private $default_value = '';
     private $has_default_value = false;
     /**
-     * 
      * If set, gives the index of a oneof in the containing type's oneof_decl
      * list.  This field is a member of that oneof.
-     * 

      *
-     * optional int32 oneof_index = 9;
+     * Generated from protobuf field optional int32 oneof_index = 9;
      */
     private $oneof_index = 0;
     private $has_oneof_index = false;
     /**
-     * 
      * JSON name of this field. The value is set by protocol compiler. If the
      * user has set a "json_name" option on this field, that option's value
      * will be used. Otherwise, it's deduced from the field's name by converting
      * it to camelCase.
-     * 

      *
-     * optional string json_name = 10;
+     * Generated from protobuf field optional string json_name = 10;
      */
     private $json_name = '';
     private $has_json_name = false;
     /**
-     * optional .google.protobuf.FieldOptions options = 8;
+     * Generated from protobuf field optional .google.protobuf.FieldOptions options = 8;
      */
     private $options = null;
     private $has_options = false;
@@ -115,7 +101,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional string name = 1;
+     * Generated from protobuf field optional string name = 1;
+     * @return string
      */
     public function getName()
     {
@@ -123,7 +110,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional string name = 1;
+     * Generated from protobuf field optional string name = 1;
+     * @param string $var
+     * @return $this
      */
     public function setName($var)
     {
@@ -140,7 +129,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional int32 number = 3;
+     * Generated from protobuf field optional int32 number = 3;
+     * @return int
      */
     public function getNumber()
     {
@@ -148,7 +138,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional int32 number = 3;
+     * Generated from protobuf field optional int32 number = 3;
+     * @param int $var
+     * @return $this
      */
     public function setNumber($var)
     {
@@ -165,7 +157,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional .google.protobuf.FieldDescriptorProto.Label label = 4;
+     * Generated from protobuf field optional .google.protobuf.FieldDescriptorProto.Label label = 4;
+     * @return int
      */
     public function getLabel()
     {
@@ -173,7 +166,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional .google.protobuf.FieldDescriptorProto.Label label = 4;
+     * Generated from protobuf field optional .google.protobuf.FieldDescriptorProto.Label label = 4;
+     * @param int $var
+     * @return $this
      */
     public function setLabel($var)
     {
@@ -190,12 +185,11 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * If type_name is set, this need not be set.  If both this and type_name
      * are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP.
-     * 

      *
-     * optional .google.protobuf.FieldDescriptorProto.Type type = 5;
+     * Generated from protobuf field optional .google.protobuf.FieldDescriptorProto.Type type = 5;
+     * @return int
      */
     public function getType()
     {
@@ -203,12 +197,12 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * If type_name is set, this need not be set.  If both this and type_name
      * are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP.
-     * 

      *
-     * optional .google.protobuf.FieldDescriptorProto.Type type = 5;
+     * Generated from protobuf field optional .google.protobuf.FieldDescriptorProto.Type type = 5;
+     * @param int $var
+     * @return $this
      */
     public function setType($var)
     {
@@ -225,15 +219,14 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * For message and enum types, this is the name of the type.  If the name
      * starts with a '.', it is fully-qualified.  Otherwise, C++-like scoping
      * rules are used to find the type (i.e. first the nested types within this
      * message are searched, then within the parent, on up to the root
      * namespace).
-     * 

      *
-     * optional string type_name = 6;
+     * Generated from protobuf field optional string type_name = 6;
+     * @return string
      */
     public function getTypeName()
     {
@@ -241,15 +234,15 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * For message and enum types, this is the name of the type.  If the name
      * starts with a '.', it is fully-qualified.  Otherwise, C++-like scoping
      * rules are used to find the type (i.e. first the nested types within this
      * message are searched, then within the parent, on up to the root
      * namespace).
-     * 

      *
-     * optional string type_name = 6;
+     * Generated from protobuf field optional string type_name = 6;
+     * @param string $var
+     * @return $this
      */
     public function setTypeName($var)
     {
@@ -266,12 +259,11 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * For extensions, this is the name of the type being extended.  It is
      * resolved in the same manner as type_name.
-     * 

      *
-     * optional string extendee = 2;
+     * Generated from protobuf field optional string extendee = 2;
+     * @return string
      */
     public function getExtendee()
     {
@@ -279,12 +271,12 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * For extensions, this is the name of the type being extended.  It is
      * resolved in the same manner as type_name.
-     * 

      *
-     * optional string extendee = 2;
+     * Generated from protobuf field optional string extendee = 2;
+     * @param string $var
+     * @return $this
      */
     public function setExtendee($var)
     {
@@ -301,15 +293,14 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * For numeric types, contains the original text representation of the value.
      * For booleans, "true" or "false".
      * For strings, contains the default text contents (not escaped in any way).
-     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
+     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
      * TODO(kenton):  Base-64 encode?
-     * 

      *
-     * optional string default_value = 7;
+     * Generated from protobuf field optional string default_value = 7;
+     * @return string
      */
     public function getDefaultValue()
     {
@@ -317,15 +308,15 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * For numeric types, contains the original text representation of the value.
      * For booleans, "true" or "false".
      * For strings, contains the default text contents (not escaped in any way).
-     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
+     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
      * TODO(kenton):  Base-64 encode?
-     * 

      *
-     * optional string default_value = 7;
+     * Generated from protobuf field optional string default_value = 7;
+     * @param string $var
+     * @return $this
      */
     public function setDefaultValue($var)
     {
@@ -342,12 +333,11 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * If set, gives the index of a oneof in the containing type's oneof_decl
      * list.  This field is a member of that oneof.
-     * 

      *
-     * optional int32 oneof_index = 9;
+     * Generated from protobuf field optional int32 oneof_index = 9;
+     * @return int
      */
     public function getOneofIndex()
     {
@@ -355,12 +345,12 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * If set, gives the index of a oneof in the containing type's oneof_decl
      * list.  This field is a member of that oneof.
-     * 

      *
-     * optional int32 oneof_index = 9;
+     * Generated from protobuf field optional int32 oneof_index = 9;
+     * @param int $var
+     * @return $this
      */
     public function setOneofIndex($var)
     {
@@ -377,14 +367,13 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * JSON name of this field. The value is set by protocol compiler. If the
      * user has set a "json_name" option on this field, that option's value
      * will be used. Otherwise, it's deduced from the field's name by converting
      * it to camelCase.
-     * 

      *
-     * optional string json_name = 10;
+     * Generated from protobuf field optional string json_name = 10;
+     * @return string
      */
     public function getJsonName()
     {
@@ -392,14 +381,14 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * 
      * JSON name of this field. The value is set by protocol compiler. If the
      * user has set a "json_name" option on this field, that option's value
      * will be used. Otherwise, it's deduced from the field's name by converting
      * it to camelCase.
-     * 

      *
-     * optional string json_name = 10;
+     * Generated from protobuf field optional string json_name = 10;
+     * @param string $var
+     * @return $this
      */
     public function setJsonName($var)
     {
@@ -416,7 +405,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional .google.protobuf.FieldOptions options = 8;
+     * Generated from protobuf field optional .google.protobuf.FieldOptions options = 8;
+     * @return \Google\Protobuf\Internal\FieldOptions
      */
     public function getOptions()
     {
@@ -424,7 +414,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * optional .google.protobuf.FieldOptions options = 8;
+     * Generated from protobuf field optional .google.protobuf.FieldOptions options = 8;
+     * @param \Google\Protobuf\Internal\FieldOptions $var
+     * @return $this
      */
     public function setOptions(&$var)
     {
-- 
cgit v1.2.3