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 <pre> 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

1 files changed, 64 insertions, 72 deletions

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;
 
 /**
- * <pre>
  * Describes a field within a message.
- * </pre>
  *
- * Protobuf type <code>google.protobuf.FieldDescriptorProto</code>
+ * Generated from protobuf message <code>google.protobuf.FieldDescriptorProto</code>
  */
 class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
 {
     /**
-     * <code>optional string name = 1;</code>
+     * Generated from protobuf field <code>optional string name = 1;</code>
      */
     private $name = '';
     private $has_name = false;
     /**
-     * <code>optional int32 number = 3;</code>
+     * Generated from protobuf field <code>optional int32 number = 3;</code>
      */
     private $number = 0;
     private $has_number = false;
     /**
-     * <code>optional .google.protobuf.FieldDescriptorProto.Label label = 4;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldDescriptorProto.Label label = 4;</code>
      */
     private $label = 0;
     private $has_label = false;
     /**
-     * <pre>
      * 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.
-     * </pre>
      *
-     * <code>optional .google.protobuf.FieldDescriptorProto.Type type = 5;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldDescriptorProto.Type type = 5;</code>
      */
     private $type = 0;
     private $has_type = false;
     /**
-     * <pre>
      * 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).
-     * </pre>
      *
-     * <code>optional string type_name = 6;</code>
+     * Generated from protobuf field <code>optional string type_name = 6;</code>
      */
     private $type_name = '';
     private $has_type_name = false;
     /**
-     * <pre>
      * For extensions, this is the name of the type being extended.  It is
      * resolved in the same manner as type_name.
-     * </pre>
      *
-     * <code>optional string extendee = 2;</code>
+     * Generated from protobuf field <code>optional string extendee = 2;</code>
      */
     private $extendee = '';
     private $has_extendee = false;
     /**
-     * <pre>
      * 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 &gt;= 128 are escaped.
+     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
      * TODO(kenton):  Base-64 encode?
-     * </pre>
      *
-     * <code>optional string default_value = 7;</code>
+     * Generated from protobuf field <code>optional string default_value = 7;</code>
      */
     private $default_value = '';
     private $has_default_value = false;
     /**
-     * <pre>
      * If set, gives the index of a oneof in the containing type's oneof_decl
      * list.  This field is a member of that oneof.
-     * </pre>
      *
-     * <code>optional int32 oneof_index = 9;</code>
+     * Generated from protobuf field <code>optional int32 oneof_index = 9;</code>
      */
     private $oneof_index = 0;
     private $has_oneof_index = false;
     /**
-     * <pre>
      * 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.
-     * </pre>
      *
-     * <code>optional string json_name = 10;</code>
+     * Generated from protobuf field <code>optional string json_name = 10;</code>
      */
     private $json_name = '';
     private $has_json_name = false;
     /**
-     * <code>optional .google.protobuf.FieldOptions options = 8;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldOptions options = 8;</code>
      */
     private $options = null;
     private $has_options = false;
@@ -115,7 +101,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional string name = 1;</code>
+     * Generated from protobuf field <code>optional string name = 1;</code>
+     * @return string
      */
     public function getName()
     {
@@ -123,7 +110,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional string name = 1;</code>
+     * Generated from protobuf field <code>optional string name = 1;</code>
+     * @param string $var
+     * @return $this
      */
     public function setName($var)
     {
@@ -140,7 +129,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional int32 number = 3;</code>
+     * Generated from protobuf field <code>optional int32 number = 3;</code>
+     * @return int
      */
     public function getNumber()
     {
@@ -148,7 +138,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional int32 number = 3;</code>
+     * Generated from protobuf field <code>optional int32 number = 3;</code>
+     * @param int $var
+     * @return $this
      */
     public function setNumber($var)
     {
@@ -165,7 +157,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.FieldDescriptorProto.Label label = 4;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldDescriptorProto.Label label = 4;</code>
+     * @return int
      */
     public function getLabel()
     {
@@ -173,7 +166,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.FieldDescriptorProto.Label label = 4;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldDescriptorProto.Label label = 4;</code>
+     * @param int $var
+     * @return $this
      */
     public function setLabel($var)
     {
@@ -190,12 +185,11 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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.
-     * </pre>
      *
-     * <code>optional .google.protobuf.FieldDescriptorProto.Type type = 5;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldDescriptorProto.Type type = 5;</code>
+     * @return int
      */
     public function getType()
     {
@@ -203,12 +197,12 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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.
-     * </pre>
      *
-     * <code>optional .google.protobuf.FieldDescriptorProto.Type type = 5;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldDescriptorProto.Type type = 5;</code>
+     * @param int $var
+     * @return $this
      */
     public function setType($var)
     {
@@ -225,15 +219,14 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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).
-     * </pre>
      *
-     * <code>optional string type_name = 6;</code>
+     * Generated from protobuf field <code>optional string type_name = 6;</code>
+     * @return string
      */
     public function getTypeName()
     {
@@ -241,15 +234,15 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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).
-     * </pre>
      *
-     * <code>optional string type_name = 6;</code>
+     * Generated from protobuf field <code>optional string type_name = 6;</code>
+     * @param string $var
+     * @return $this
      */
     public function setTypeName($var)
     {
@@ -266,12 +259,11 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * For extensions, this is the name of the type being extended.  It is
      * resolved in the same manner as type_name.
-     * </pre>
      *
-     * <code>optional string extendee = 2;</code>
+     * Generated from protobuf field <code>optional string extendee = 2;</code>
+     * @return string
      */
     public function getExtendee()
     {
@@ -279,12 +271,12 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * For extensions, this is the name of the type being extended.  It is
      * resolved in the same manner as type_name.
-     * </pre>
      *
-     * <code>optional string extendee = 2;</code>
+     * Generated from protobuf field <code>optional string extendee = 2;</code>
+     * @param string $var
+     * @return $this
      */
     public function setExtendee($var)
     {
@@ -301,15 +293,14 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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 &gt;= 128 are escaped.
+     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
      * TODO(kenton):  Base-64 encode?
-     * </pre>
      *
-     * <code>optional string default_value = 7;</code>
+     * Generated from protobuf field <code>optional string default_value = 7;</code>
+     * @return string
      */
     public function getDefaultValue()
     {
@@ -317,15 +308,15 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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 &gt;= 128 are escaped.
+     * For bytes, contains the C escaped value.  All bytes >= 128 are escaped.
      * TODO(kenton):  Base-64 encode?
-     * </pre>
      *
-     * <code>optional string default_value = 7;</code>
+     * Generated from protobuf field <code>optional string default_value = 7;</code>
+     * @param string $var
+     * @return $this
      */
     public function setDefaultValue($var)
     {
@@ -342,12 +333,11 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * If set, gives the index of a oneof in the containing type's oneof_decl
      * list.  This field is a member of that oneof.
-     * </pre>
      *
-     * <code>optional int32 oneof_index = 9;</code>
+     * Generated from protobuf field <code>optional int32 oneof_index = 9;</code>
+     * @return int
      */
     public function getOneofIndex()
     {
@@ -355,12 +345,12 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * If set, gives the index of a oneof in the containing type's oneof_decl
      * list.  This field is a member of that oneof.
-     * </pre>
      *
-     * <code>optional int32 oneof_index = 9;</code>
+     * Generated from protobuf field <code>optional int32 oneof_index = 9;</code>
+     * @param int $var
+     * @return $this
      */
     public function setOneofIndex($var)
     {
@@ -377,14 +367,13 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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.
-     * </pre>
      *
-     * <code>optional string json_name = 10;</code>
+     * Generated from protobuf field <code>optional string json_name = 10;</code>
+     * @return string
      */
     public function getJsonName()
     {
@@ -392,14 +381,14 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * 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.
-     * </pre>
      *
-     * <code>optional string json_name = 10;</code>
+     * Generated from protobuf field <code>optional string json_name = 10;</code>
+     * @param string $var
+     * @return $this
      */
     public function setJsonName($var)
     {
@@ -416,7 +405,8 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.FieldOptions options = 8;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldOptions options = 8;</code>
+     * @return \Google\Protobuf\Internal\FieldOptions
      */
     public function getOptions()
     {
@@ -424,7 +414,9 @@ class FieldDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.FieldOptions options = 8;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FieldOptions options = 8;</code>
+     * @param \Google\Protobuf\Internal\FieldOptions $var
+     * @return $this
      */
     public function setOptions(&$var)
     {