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, 25 insertions, 37 deletions

diff --git a/php/src/Google/Protobuf/Internal/GeneratedCodeInfo_Annotation.php b/php/src/Google/Protobuf/Internal/GeneratedCodeInfo_Annotation.php
index 8d227e1c..c2e22e89 100644
--- a/php/src/Google/Protobuf/Internal/GeneratedCodeInfo_Annotation.php
+++ b/php/src/Google/Protobuf/Internal/GeneratedCodeInfo_Annotation.php
@@ -12,47 +12,39 @@ use Google\Protobuf\Internal\InputStream;
 use Google\Protobuf\Internal\GPBUtil;
 
 /**
- * Protobuf type <code>google.protobuf.GeneratedCodeInfo.Annotation</code>
+ * Generated from protobuf message <code>google.protobuf.GeneratedCodeInfo.Annotation</code>
  */
 class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
 {
     /**
-     * <pre>
      * Identifies the element in the original source .proto file. This field
      * is formatted the same as SourceCodeInfo.Location.path.
-     * </pre>
      *
-     * <code>repeated int32 path = 1 [packed = true];</code>
+     * Generated from protobuf field <code>repeated int32 path = 1 [packed = true];</code>
      */
     private $path;
     private $has_path = false;
     /**
-     * <pre>
      * Identifies the filesystem path to the original source .proto.
-     * </pre>
      *
-     * <code>optional string source_file = 2;</code>
+     * Generated from protobuf field <code>optional string source_file = 2;</code>
      */
     private $source_file = '';
     private $has_source_file = false;
     /**
-     * <pre>
      * Identifies the starting offset in bytes in the generated code
      * that relates to the identified object.
-     * </pre>
      *
-     * <code>optional int32 begin = 3;</code>
+     * Generated from protobuf field <code>optional int32 begin = 3;</code>
      */
     private $begin = 0;
     private $has_begin = false;
     /**
-     * <pre>
      * Identifies the ending offset in bytes in the generated code that
      * relates to the identified offset. The end offset should be one past
      * the last relevant byte (so the length of the text = end - begin).
-     * </pre>
      *
-     * <code>optional int32 end = 4;</code>
+     * Generated from protobuf field <code>optional int32 end = 4;</code>
      */
     private $end = 0;
     private $has_end = false;
@@ -63,12 +55,11 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the element in the original source .proto file. This field
      * is formatted the same as SourceCodeInfo.Location.path.
-     * </pre>
      *
-     * <code>repeated int32 path = 1 [packed = true];</code>
+     * Generated from protobuf field <code>repeated int32 path = 1 [packed = true];</code>
+     * @return \Google\Protobuf\Internal\RepeatedField
      */
     public function getPath()
     {
@@ -76,12 +67,12 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the element in the original source .proto file. This field
      * is formatted the same as SourceCodeInfo.Location.path.
-     * </pre>
      *
-     * <code>repeated int32 path = 1 [packed = true];</code>
+     * Generated from protobuf field <code>repeated int32 path = 1 [packed = true];</code>
+     * @param int[]|\Google\Protobuf\Internal\RepeatedField $var
+     * @return $this
      */
     public function setPath(&$var)
     {
@@ -98,11 +89,10 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the filesystem path to the original source .proto.
-     * </pre>
      *
-     * <code>optional string source_file = 2;</code>
+     * Generated from protobuf field <code>optional string source_file = 2;</code>
+     * @return string
      */
     public function getSourceFile()
     {
@@ -110,11 +100,11 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the filesystem path to the original source .proto.
-     * </pre>
      *
-     * <code>optional string source_file = 2;</code>
+     * Generated from protobuf field <code>optional string source_file = 2;</code>
+     * @param string $var
+     * @return $this
      */
     public function setSourceFile($var)
     {
@@ -131,12 +121,11 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the starting offset in bytes in the generated code
      * that relates to the identified object.
-     * </pre>
      *
-     * <code>optional int32 begin = 3;</code>
+     * Generated from protobuf field <code>optional int32 begin = 3;</code>
+     * @return int
      */
     public function getBegin()
     {
@@ -144,12 +133,12 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the starting offset in bytes in the generated code
      * that relates to the identified object.
-     * </pre>
      *
-     * <code>optional int32 begin = 3;</code>
+     * Generated from protobuf field <code>optional int32 begin = 3;</code>
+     * @param int $var
+     * @return $this
      */
     public function setBegin($var)
     {
@@ -166,13 +155,12 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the ending offset in bytes in the generated code that
      * relates to the identified offset. The end offset should be one past
      * the last relevant byte (so the length of the text = end - begin).
-     * </pre>
      *
-     * <code>optional int32 end = 4;</code>
+     * Generated from protobuf field <code>optional int32 end = 4;</code>
+     * @return int
      */
     public function getEnd()
     {
@@ -180,13 +168,13 @@ class GeneratedCodeInfo_Annotation extends \Google\Protobuf\Internal\Message
     }
 
     /**
-     * <pre>
      * Identifies the ending offset in bytes in the generated code that
      * relates to the identified offset. The end offset should be one past
      * the last relevant byte (so the length of the text = end - begin).
-     * </pre>
      *
-     * <code>optional int32 end = 4;</code>
+     * Generated from protobuf field <code>optional int32 end = 4;</code>
+     * @param int $var
+     * @return $this
      */
     public function setEnd($var)
     {