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, 34 insertions, 49 deletions

diff --git a/php/src/Google/Protobuf/Internal/MessageOptions.php b/php/src/Google/Protobuf/Internal/MessageOptions.php
index a5835358..3677ca38 100644
--- a/php/src/Google/Protobuf/Internal/MessageOptions.php
+++ b/php/src/Google/Protobuf/Internal/MessageOptions.php
@@ -12,12 +12,11 @@ use Google\Protobuf\Internal\InputStream;
 use Google\Protobuf\Internal\GPBUtil;
 
 /**
- * Protobuf type <code>google.protobuf.MessageOptions</code>
+ * Generated from protobuf message <code>google.protobuf.MessageOptions</code>
  */
 class MessageOptions extends \Google\Protobuf\Internal\Message
 {
     /**
-     * <pre>
      * Set true to use the old proto1 MessageSet wire format for extensions.
      * This is provided for backwards-compatibility with the MessageSet wire
      * format.  You should not use this for any other reason:  It's less
@@ -33,41 +32,35 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
      * be int32s, enums, or repeated messages.
      * Because this is an option, the above two restrictions are not enforced by
      * the protocol compiler.
-     * </pre>
      *
-     * <code>optional bool message_set_wire_format = 1 [default = false];</code>
+     * Generated from protobuf field <code>optional bool message_set_wire_format = 1 [default = false];</code>
      */
     private $message_set_wire_format = false;
     private $has_message_set_wire_format = false;
     /**
-     * <pre>
      * Disables the generation of the standard "descriptor()" accessor, which can
      * conflict with a field of the same name.  This is meant to make migration
      * from proto1 easier; new code should avoid fields named "descriptor".
-     * </pre>
      *
-     * <code>optional bool no_standard_descriptor_accessor = 2 [default = false];</code>
+     * Generated from protobuf field <code>optional bool no_standard_descriptor_accessor = 2 [default = false];</code>
      */
     private $no_standard_descriptor_accessor = false;
     private $has_no_standard_descriptor_accessor = false;
     /**
-     * <pre>
      * Is this message deprecated?
      * Depending on the target platform, this can emit Deprecated annotations
      * for the message, or it will be completely ignored; in the very least,
      * this is a formalization for deprecating messages.
-     * </pre>
      *
-     * <code>optional bool deprecated = 3 [default = false];</code>
+     * Generated from protobuf field <code>optional bool deprecated = 3 [default = false];</code>
      */
     private $deprecated = false;
     private $has_deprecated = false;
     /**
-     * <pre>
      * Whether the message is an automatically generated map entry type for the
      * maps field.
      * For maps fields:
-     *     map&lt;KeyType, ValueType&gt; map_field = 1;
+     *     map<KeyType, ValueType> map_field = 1;
      * The parsed descriptor looks like:
      *     message MapFieldEntry {
      *         option map_entry = true;
@@ -82,18 +75,15 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
      * NOTE: Do not set the option in .proto files. Always use the maps syntax
      * instead. The option should only be implicitly set by the proto compiler
      * parser.
-     * </pre>
      *
-     * <code>optional bool map_entry = 7;</code>
+     * Generated from protobuf field <code>optional bool map_entry = 7;</code>
      */
     private $map_entry = false;
     private $has_map_entry = false;
     /**
-     * <pre>
      * The parser stores options it doesn't recognize here. See above.
-     * </pre>
      *
-     * <code>repeated .google.protobuf.UninterpretedOption uninterpreted_option = 999;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.UninterpretedOption uninterpreted_option = 999;</code>
      */
     private $uninterpreted_option;
     private $has_uninterpreted_option = false;
@@ -104,7 +94,6 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Set true to use the old proto1 MessageSet wire format for extensions.
      * This is provided for backwards-compatibility with the MessageSet wire
      * format.  You should not use this for any other reason:  It's less
@@ -120,9 +109,9 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
      * be int32s, enums, or repeated messages.
      * Because this is an option, the above two restrictions are not enforced by
      * the protocol compiler.
-     * </pre>
      *
-     * <code>optional bool message_set_wire_format = 1 [default = false];</code>
+     * Generated from protobuf field <code>optional bool message_set_wire_format = 1 [default = false];</code>
+     * @return bool
      */
     public function getMessageSetWireFormat()
     {
@@ -130,7 +119,6 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Set true to use the old proto1 MessageSet wire format for extensions.
      * This is provided for backwards-compatibility with the MessageSet wire
      * format.  You should not use this for any other reason:  It's less
@@ -146,9 +134,10 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
      * be int32s, enums, or repeated messages.
      * Because this is an option, the above two restrictions are not enforced by
      * the protocol compiler.
-     * </pre>
      *
-     * <code>optional bool message_set_wire_format = 1 [default = false];</code>
+     * Generated from protobuf field <code>optional bool message_set_wire_format = 1 [default = false];</code>
+     * @param bool $var
+     * @return $this
      */
     public function setMessageSetWireFormat($var)
     {
@@ -165,13 +154,12 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Disables the generation of the standard "descriptor()" accessor, which can
      * conflict with a field of the same name.  This is meant to make migration
      * from proto1 easier; new code should avoid fields named "descriptor".
-     * </pre>
      *
-     * <code>optional bool no_standard_descriptor_accessor = 2 [default = false];</code>
+     * Generated from protobuf field <code>optional bool no_standard_descriptor_accessor = 2 [default = false];</code>
+     * @return bool
      */
     public function getNoStandardDescriptorAccessor()
     {
@@ -179,13 +167,13 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Disables the generation of the standard "descriptor()" accessor, which can
      * conflict with a field of the same name.  This is meant to make migration
      * from proto1 easier; new code should avoid fields named "descriptor".
-     * </pre>
      *
-     * <code>optional bool no_standard_descriptor_accessor = 2 [default = false];</code>
+     * Generated from protobuf field <code>optional bool no_standard_descriptor_accessor = 2 [default = false];</code>
+     * @param bool $var
+     * @return $this
      */
     public function setNoStandardDescriptorAccessor($var)
     {
@@ -202,14 +190,13 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Is this message deprecated?
      * Depending on the target platform, this can emit Deprecated annotations
      * for the message, or it will be completely ignored; in the very least,
      * this is a formalization for deprecating messages.
-     * </pre>
      *
-     * <code>optional bool deprecated = 3 [default = false];</code>
+     * Generated from protobuf field <code>optional bool deprecated = 3 [default = false];</code>
+     * @return bool
      */
     public function getDeprecated()
     {
@@ -217,14 +204,14 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Is this message deprecated?
      * Depending on the target platform, this can emit Deprecated annotations
      * for the message, or it will be completely ignored; in the very least,
      * this is a formalization for deprecating messages.
-     * </pre>
      *
-     * <code>optional bool deprecated = 3 [default = false];</code>
+     * Generated from protobuf field <code>optional bool deprecated = 3 [default = false];</code>
+     * @param bool $var
+     * @return $this
      */
     public function setDeprecated($var)
     {
@@ -241,11 +228,10 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Whether the message is an automatically generated map entry type for the
      * maps field.
      * For maps fields:
-     *     map&lt;KeyType, ValueType&gt; map_field = 1;
+     *     map<KeyType, ValueType> map_field = 1;
      * The parsed descriptor looks like:
      *     message MapFieldEntry {
      *         option map_entry = true;
@@ -260,9 +246,9 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
      * NOTE: Do not set the option in .proto files. Always use the maps syntax
      * instead. The option should only be implicitly set by the proto compiler
      * parser.
-     * </pre>
      *
-     * <code>optional bool map_entry = 7;</code>
+     * Generated from protobuf field <code>optional bool map_entry = 7;</code>
+     * @return bool
      */
     public function getMapEntry()
     {
@@ -270,11 +256,10 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Whether the message is an automatically generated map entry type for the
      * maps field.
      * For maps fields:
-     *     map&lt;KeyType, ValueType&gt; map_field = 1;
+     *     map<KeyType, ValueType> map_field = 1;
      * The parsed descriptor looks like:
      *     message MapFieldEntry {
      *         option map_entry = true;
@@ -289,9 +274,10 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
      * NOTE: Do not set the option in .proto files. Always use the maps syntax
      * instead. The option should only be implicitly set by the proto compiler
      * parser.
-     * </pre>
      *
-     * <code>optional bool map_entry = 7;</code>
+     * Generated from protobuf field <code>optional bool map_entry = 7;</code>
+     * @param bool $var
+     * @return $this
      */
     public function setMapEntry($var)
     {
@@ -308,11 +294,10 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * The parser stores options it doesn't recognize here. See above.
-     * </pre>
      *
-     * <code>repeated .google.protobuf.UninterpretedOption uninterpreted_option = 999;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.UninterpretedOption uninterpreted_option = 999;</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getUninterpretedOption()
     {
@@ -320,11 +305,11 @@ class MessageOptions extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * The parser stores options it doesn't recognize here. See above.
-     * </pre>
      *
-     * <code>repeated .google.protobuf.UninterpretedOption uninterpreted_option = 999;</code>
+     * Generated from protobuf field <code>repeated .google.protobuf.UninterpretedOption uninterpreted_option = 999;</code>
+     * @param \Google\Protobuf\Internal\UninterpretedOption[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setUninterpretedOption(&$var)
     {