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, 73 insertions, 87 deletions

diff --git a/php/src/Google/Protobuf/Internal/FileDescriptorProto.php b/php/src/Google/Protobuf/Internal/FileDescriptorProto.php
index b229522a..3b1567d1 100644
--- a/php/src/Google/Protobuf/Internal/FileDescriptorProto.php
+++ b/php/src/Google/Protobuf/Internal/FileDescriptorProto.php
@@ -12,108 +12,90 @@ use Google\Protobuf\Internal\InputStream;
 use Google\Protobuf\Internal\GPBUtil;
 
 /**
- * <pre>
  * Describes a complete .proto file.
- * </pre>
  *
- * Protobuf type <code>google.protobuf.FileDescriptorProto</code>
+ * Generated from protobuf message <code>google.protobuf.FileDescriptorProto</code>
  */
 class FileDescriptorProto extends \Google\Protobuf\Internal\Message
 {
     /**
-     * <pre>
      * file name, relative to root of source tree
-     * </pre>
      *
-     * <code>optional string name = 1;</code>
+     * Generated from protobuf field <code>optional string name = 1;</code>
      */
     private $name = '';
     private $has_name = false;
     /**
-     * <pre>
      * e.g. "foo", "foo.bar", etc.
-     * </pre>
      *
-     * <code>optional string package = 2;</code>
+     * Generated from protobuf field <code>optional string package = 2;</code>
      */
     private $package = '';
     private $has_package = false;
     /**
-     * <pre>
      * Names of files imported by this file.
-     * </pre>
      *
-     * <code>repeated string dependency = 3;</code>
+     * Generated from protobuf field <code>repeated string dependency = 3;</code>
      */
     private $dependency;
     private $has_dependency = false;
     /**
-     * <pre>
      * Indexes of the public imported files in the dependency list above.
-     * </pre>
      *
-     * <code>repeated int32 public_dependency = 10;</code>
+     * Generated from protobuf field <code>repeated int32 public_dependency = 10;</code>
      */
     private $public_dependency;
     private $has_public_dependency = false;
     /**
-     * <pre>
      * Indexes of the weak imported files in the dependency list.
      * For Google-internal migration only. Do not use.
-     * </pre>
      *
-     * <code>repeated int32 weak_dependency = 11;</code>
+     * Generated from protobuf field <code>repeated int32 weak_dependency = 11;</code>
      */
     private $weak_dependency;
     private $has_weak_dependency = false;
     /**
-     * <pre>
      * All top-level definitions in this file.
-     * </pre>
      *
-     * <code>repeated .google.protobuf.DescriptorProto message_type = 4;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto message_type = 4;</code>
      */
     private $message_type;
     private $has_message_type = false;
     /**
-     * <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 5;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 5;</code>
      */
     private $enum_type;
     private $has_enum_type = false;
     /**
-     * <code>repeated .google.protobuf.ServiceDescriptorProto service = 6;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.ServiceDescriptorProto service = 6;</code>
      */
     private $service;
     private $has_service = false;
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto extension = 7;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto extension = 7;</code>
      */
     private $extension;
     private $has_extension = false;
     /**
-     * <code>optional .google.protobuf.FileOptions options = 8;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FileOptions options = 8;</code>
      */
     private $options = null;
     private $has_options = false;
     /**
-     * <pre>
      * This field contains optional information about the original source code.
      * You may safely remove this entire field without harming runtime
      * functionality of the descriptors -- the information is needed only by
      * development tools.
-     * </pre>
      *
-     * <code>optional .google.protobuf.SourceCodeInfo source_code_info = 9;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.SourceCodeInfo source_code_info = 9;</code>
      */
     private $source_code_info = null;
     private $has_source_code_info = false;
     /**
-     * <pre>
      * The syntax of the proto file.
      * The supported values are "proto2" and "proto3".
-     * </pre>
      *
-     * <code>optional string syntax = 12;</code>
+     * Generated from protobuf field <code>optional string syntax = 12;</code>
      */
     private $syntax = '';
     private $has_syntax = false;
@@ -124,11 +106,10 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * file name, relative to root of source tree
-     * </pre>
      *
-     * <code>optional string name = 1;</code>
+     * Generated from protobuf field <code>optional string name = 1;</code>
+     * @return string
      */
     public function getName()
     {
@@ -136,11 +117,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * file name, relative to root of source tree
-     * </pre>
      *
-     * <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)
     {
@@ -157,11 +138,10 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * e.g. "foo", "foo.bar", etc.
-     * </pre>
      *
-     * <code>optional string package = 2;</code>
+     * Generated from protobuf field <code>optional string package = 2;</code>
+     * @return string
      */
     public function getPackage()
     {
@@ -169,11 +149,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * e.g. "foo", "foo.bar", etc.
-     * </pre>
      *
-     * <code>optional string package = 2;</code>
+     * Generated from protobuf field <code>optional string package = 2;</code>
+     * @param string $var
+     * @return $this
      */
     public function setPackage($var)
     {
@@ -190,11 +170,10 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Names of files imported by this file.
-     * </pre>
      *
-     * <code>repeated string dependency = 3;</code>
+     * Generated from protobuf field <code>repeated string dependency = 3;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getDependency()
     {
@@ -202,11 +181,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Names of files imported by this file.
-     * </pre>
      *
-     * <code>repeated string dependency = 3;</code>
+     * Generated from protobuf field <code>repeated string dependency = 3;</code>
+     * @param string[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setDependency(&$var)
     {
@@ -223,11 +202,10 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Indexes of the public imported files in the dependency list above.
-     * </pre>
      *
-     * <code>repeated int32 public_dependency = 10;</code>
+     * Generated from protobuf field <code>repeated int32 public_dependency = 10;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getPublicDependency()
     {
@@ -235,11 +213,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Indexes of the public imported files in the dependency list above.
-     * </pre>
      *
-     * <code>repeated int32 public_dependency = 10;</code>
+     * Generated from protobuf field <code>repeated int32 public_dependency = 10;</code>
+     * @param int[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setPublicDependency(&$var)
     {
@@ -256,12 +234,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Indexes of the weak imported files in the dependency list.
      * For Google-internal migration only. Do not use.
-     * </pre>
      *
-     * <code>repeated int32 weak_dependency = 11;</code>
+     * Generated from protobuf field <code>repeated int32 weak_dependency = 11;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getWeakDependency()
     {
@@ -269,12 +246,12 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Indexes of the weak imported files in the dependency list.
      * For Google-internal migration only. Do not use.
-     * </pre>
      *
-     * <code>repeated int32 weak_dependency = 11;</code>
+     * Generated from protobuf field <code>repeated int32 weak_dependency = 11;</code>
+     * @param int[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setWeakDependency(&$var)
     {
@@ -291,11 +268,10 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * All top-level definitions in this file.
-     * </pre>
      *
-     * <code>repeated .google.protobuf.DescriptorProto message_type = 4;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto message_type = 4;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getMessageType()
     {
@@ -303,11 +279,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * All top-level definitions in this file.
-     * </pre>
      *
-     * <code>repeated .google.protobuf.DescriptorProto message_type = 4;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.DescriptorProto message_type = 4;</code>
+     * @param \Google\Protobuf\Internal\DescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setMessageType(&$var)
     {
@@ -324,7 +300,8 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 5;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 5;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getEnumType()
     {
@@ -332,7 +309,9 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 5;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.EnumDescriptorProto enum_type = 5;</code>
+     * @param \Google\Protobuf\Internal\EnumDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setEnumType(&$var)
     {
@@ -349,7 +328,8 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.ServiceDescriptorProto service = 6;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.ServiceDescriptorProto service = 6;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getService()
     {
@@ -357,7 +337,9 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.ServiceDescriptorProto service = 6;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.ServiceDescriptorProto service = 6;</code>
+     * @param \Google\Protobuf\Internal\ServiceDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setService(&$var)
     {
@@ -374,7 +356,8 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto extension = 7;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto extension = 7;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getExtension()
     {
@@ -382,7 +365,9 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>repeated .google.protobuf.FieldDescriptorProto extension = 7;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.FieldDescriptorProto extension = 7;</code>
+     * @param \Google\Protobuf\Internal\FieldDescriptorProto[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setExtension(&$var)
     {
@@ -399,7 +384,8 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.FileOptions options = 8;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FileOptions options = 8;</code>
+     * @return \Google\Protobuf\Internal\FileOptions
      */
     public function getOptions()
     {
@@ -407,7 +393,9 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <code>optional .google.protobuf.FileOptions options = 8;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.FileOptions options = 8;</code>
+     * @param \Google\Protobuf\Internal\FileOptions $var
+     * @return $this
      */
     public function setOptions(&$var)
     {
@@ -424,14 +412,13 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * This field contains optional information about the original source code.
      * You may safely remove this entire field without harming runtime
      * functionality of the descriptors -- the information is needed only by
      * development tools.
-     * </pre>
      *
-     * <code>optional .google.protobuf.SourceCodeInfo source_code_info = 9;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.SourceCodeInfo source_code_info = 9;</code>
+     * @return \Google\Protobuf\Internal\SourceCodeInfo
      */
     public function getSourceCodeInfo()
     {
@@ -439,14 +426,14 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * This field contains optional information about the original source code.
      * You may safely remove this entire field without harming runtime
      * functionality of the descriptors -- the information is needed only by
      * development tools.
-     * </pre>
      *
-     * <code>optional .google.protobuf.SourceCodeInfo source_code_info = 9;</code>
+     * Generated from protobuf field <code>optional .google.protobuf.SourceCodeInfo source_code_info = 9;</code>
+     * @param \Google\Protobuf\Internal\SourceCodeInfo $var
+     * @return $this
      */
     public function setSourceCodeInfo(&$var)
     {
@@ -463,12 +450,11 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * The syntax of the proto file.
      * The supported values are "proto2" and "proto3".
-     * </pre>
      *
-     * <code>optional string syntax = 12;</code>
+     * Generated from protobuf field <code>optional string syntax = 12;</code>
+     * @return string
      */
     public function getSyntax()
     {
@@ -476,12 +462,12 @@ class FileDescriptorProto extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * The syntax of the proto file.
      * The supported values are "proto2" and "proto3".
-     * </pre>
      *
-     * <code>optional string syntax = 12;</code>
+     * Generated from protobuf field <code>optional string syntax = 12;</code>
+     * @param string $var
+     * @return $this
      */
     public function setSyntax($var)
     {