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, 61 insertions, 39 deletions

diff --git a/php/src/Google/Protobuf/Internal/DescriptorProto.php b/php/src/Google/Protobuf/Internal/DescriptorProto.php
index c72c0962..0fdaecfc 100644
--- a/php/src/Google/Protobuf/Internal/DescriptorProto.php
+++ b/php/src/Google/Protobuf/Internal/DescriptorProto.php
@@ -12,66 +12,62 @@ use Google\Protobuf\Internal\InputStream;
 use Google\Protobuf\Internal\GPBUtil;
 
 /**
- * <pre>
  * Describes a message type.
- * </pre>
  *
- * Protobuf type <code>google.protobuf.DescriptorProto</code>
+ * Generated from protobuf message <code>google.protobuf.DescriptorProto</code>
  */
 class DescriptorProto 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>repeated .google.protobuf.FieldDescriptorProto field = 2;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto field = 2;</code>
      */
     private $field;
     private $has_field = false;
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto extension = 6;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto extension = 6;</code>
      */
     private $extension;
     private $has_extension = false;
     /**
-     * <code>repeated .google.protobuf.DescriptorProto nested_type = 3;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto nested_type = 3;</code>
      */
     private $nested_type;
     private $has_nested_type = false;
     /**
-     * <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 4;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 4;</code>
      */
     private $enum_type;
     private $has_enum_type = false;
     /**
-     * <code>repeated .google.protobuf.DescriptorProto.ExtensionRange extension_range = 5;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto.ExtensionRange extension_range = 5;</code>
      */
     private $extension_range;
     private $has_extension_range = false;
     /**
-     * <code>repeated .google.protobuf.OneofDescriptorProto oneof_decl = 8;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.OneofDescriptorProto oneof_decl = 8;</code>
      */
     private $oneof_decl;
     private $has_oneof_decl = false;
     /**
-     * <code>optional .google.protobuf.MessageOptions options = 7;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.MessageOptions options = 7;</code>
      */
     private $options = null;
     private $has_options = false;
     /**
-     * <code>repeated .google.protobuf.DescriptorProto.ReservedRange reserved_range = 9;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto.ReservedRange reserved_range = 9;</code>
      */
     private $reserved_range;
     private $has_reserved_range = false;
     /**
-     * <pre>
      * Reserved field names, which may not be used by fields in the same message.
      * A given name may only be reserved once.
-     * </pre>
      *
-     * <code>repeated string reserved_name = 10;</code>
+     * Generated from protobuf field <code>repeated string reserved_name = 10;</code>
      */
     private $reserved_name;
     private $has_reserved_name = false;
@@ -82,7 +78,8 @@ class DescriptorProto 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()
     {
@@ -90,7 +87,9 @@ class DescriptorProto 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)
     {
@@ -107,7 +106,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto field = 2;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto field = 2;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getField()
     {
@@ -115,7 +115,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto field = 2;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto field = 2;</code>
+     * @param \Google\Protobuf\Internal\FieldDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setField(&$var)
     {
@@ -132,7 +134,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto extension = 6;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto extension = 6;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getExtension()
     {
@@ -140,7 +143,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto extension = 6;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto extension = 6;</code>
+     * @param \Google\Protobuf\Internal\FieldDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setExtension(&$var)
     {
@@ -157,7 +162,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.DescriptorProto nested_type = 3;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto nested_type = 3;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getNestedType()
     {
@@ -165,7 +171,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.DescriptorProto nested_type = 3;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto nested_type = 3;</code>
+     * @param \Google\Protobuf\Internal\DescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setNestedType(&$var)
     {
@@ -182,7 +190,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 4;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 4;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getEnumType()
     {
@@ -190,7 +199,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 4;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 4;</code>
+     * @param \Google\Protobuf\Internal\EnumDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setEnumType(&$var)
     {
@@ -207,7 +218,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.DescriptorProto.ExtensionRange extension_range = 5;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto.ExtensionRange extension_range = 5;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getExtensionRange()
     {
@@ -215,7 +227,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.DescriptorProto.ExtensionRange extension_range = 5;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto.ExtensionRange extension_range = 5;</code>
+     * @param \Google\Protobuf\Internal\DescriptorProto_ExtensionRange[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setExtensionRange(&$var)
     {
@@ -232,7 +246,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.OneofDescriptorProto oneof_decl = 8;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.OneofDescriptorProto oneof_decl = 8;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getOneofDecl()
     {
@@ -240,7 +255,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.OneofDescriptorProto oneof_decl = 8;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.OneofDescriptorProto oneof_decl = 8;</code>
+     * @param \Google\Protobuf\Internal\OneofDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setOneofDecl(&$var)
     {
@@ -257,7 +274,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.MessageOptions options = 7;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.MessageOptions options = 7;</code>
+     * @return \Google\Protobuf\Internal\MessageOptions
      */
     public function getOptions()
     {
@@ -265,7 +283,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.MessageOptions options = 7;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.MessageOptions options = 7;</code>
+     * @param \Google\Protobuf\Internal\MessageOptions $var
+     * @return $this
      */
     public function setOptions(&$var)
     {
@@ -282,7 +302,8 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.DescriptorProto.ReservedRange reserved_range = 9;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto.ReservedRange reserved_range = 9;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getReservedRange()
     {
@@ -290,7 +311,9 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.DescriptorProto.ReservedRange reserved_range = 9;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto.ReservedRange reserved_range = 9;</code>
+     * @param \Google\Protobuf\Internal\DescriptorProto_ReservedRange[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setReservedRange(&$var)
     {
@@ -307,12 +330,11 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Reserved field names, which may not be used by fields in the same message.
      * A given name may only be reserved once.
-     * </pre>
      *
-     * <code>repeated string reserved_name = 10;</code>
+     * Generated from protobuf field <code>repeated string reserved_name = 10;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getReservedName()
     {
@@ -320,12 +342,12 @@ class DescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Reserved field names, which may not be used by fields in the same message.
      * A given name may only be reserved once.
-     * </pre>
      *
-     * <code>repeated string reserved_name = 10;</code>
+     * Generated from protobuf field <code>repeated string reserved_name = 10;</code>
+     * @param string[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setReservedName(&$var)
     {