Add NodeAbstract::setDocComment()

CHANGELOG.md

@@ -1,10 +1,13 @@
 Version 3.0.0-dev
 -----------------
 
-Nothing yet.
+### Added
+
+* Added `NodeAbstract::setDocComment()` method.
 
 Version 3.0.0-beta1 (2016-09-16)
 --------------------------------
+
 ### Added
 
 * [7.1] Function/method and parameter builders now support PHP 7.1 type hints (void, iterable and
@@ -20,7 +23,7 @@ Version 3.0.0-beta1 (2016-09-16)
 The following changes are also part of PHP-Parser 2.1.1:
 
 * The PHP 7 parser will now generate a parse error for `$var =& new Obj` assignments.
-* Comments on free-standing code blocks will no be retained as comments on the first statement in
+* Comments on free-standing code blocks will now be retained as comments on the first statement in
   the code block.
 
 Version 3.0.0-alpha1 (2016-07-25)

lib/PhpParser/NodeAbstract.php

@@ -63,6 +63,28 @@ abstract class NodeAbstract implements Node, \JsonSerializable
         return $lastComment;
     }
 
+    /**
+     * Sets the doc comment of the node.
+     *
+     * This will either replace an existing doc comment or add it to the comments array.
+     *
+     * @param Comment\Doc $docComment Doc comment to set
+     */
+    public function setDocComment(Comment\Doc $docComment) {
+        $comments = $this->getAttribute('comments', []);
+
+        $numComments = count($comments);
+        if ($numComments > 0 && $comments[$numComments - 1] instanceof Comment\Doc) {
+            // Replace existing doc comment
+            $comments[$numComments - 1] = $docComment;
+        } else {
+            // Append new comment
+            $comments[] = $docComment;
+        }
+
+        $this->setAttribute('comments', $comments);
+    }
+
     public function setAttribute($key, $value) {
         $this->attributes[$key] = $value;
     }

test/PhpParser/NodeAbstractTest.php

@@ -70,6 +70,28 @@ class NodeAbstractTest extends \PHPUnit_Framework_TestCase
         $this->assertNull($node->getDocComment());
     }
 
+    public function testSetDocComment() {
+        $node = new DummyNode(null, null, []);
+
+        // Add doc comment to node without comments
+        $docComment = new Comment\Doc('/** doc */');
+        $node->setDocComment($docComment);
+        $this->assertSame($docComment, $node->getDocComment());
+
+        // Replace it
+        $docComment = new Comment\Doc('/** doc 2 */');
+        $node->setDocComment($docComment);
+        $this->assertSame($docComment, $node->getDocComment());
+
+        // Add docmment to node with other comments
+        $c1 = new Comment('/* foo */');
+        $c2 = new Comment('/* bar */');
+        $docComment = new Comment\Doc('/** baz */');
+        $node->setAttribute('comments', [$c1, $c2]);
+        $node->setDocComment($docComment);
+        $this->assertSame([$c1, $c2, $docComment], $node->getAttribute('comments'));
+    }
+
     /**
      * @dataProvider provideNodes
      */