Add support for doc comments in builders

doc/4_Code_generation.markdown

@@ -19,6 +19,11 @@ $node = $factory->class('SomeClass')
     ->addStmt($factory->method('someMethod')
         ->makeAbstract() // ->makeFinal()
         ->addParam($factory->param('someParam')->setTypeHint('SomeClass'))
+        ->setDocComment('/**
+                          * This method does something.
+                          *
+                          * @param SomeClass And takes a parameter
+                          */')
     )
 
     ->addStmt($factory->method('anotherMethod')
@@ -49,7 +54,12 @@ abstract class SomeClass extends SomeOtherClass implements A\Few, Interfaces
 {
     protected $someProperty;
     private $anotherProperty = array(1, 2, 3);
-    abstract function someMethod(SomeClass $someParam);
+    /**
+     * This method does something.
+     *
+     * @param SomeClass And takes a parameter
+     */
+    public abstract function someMethod(SomeClass $someParam);
     protected function anotherMethod($someParam = 'test')
     {
         print $someParam;

lib/PhpParser/Builder/Class_.php

@@ -19,6 +19,8 @@ class Class_ extends PhpParser\BuilderAbstract
     protected $properties;
     protected $methods;
 
+    protected $attributes;
+
     /**
      * Creates a class builder.
      *
@@ -32,6 +34,7 @@ class Class_ extends PhpParser\BuilderAbstract
         $this->implements = array();
 
         $this->uses = $this->constants = $this->properties = $this->methods = array();
+        $this->attributes = array();
     }
 
     /**
@@ -127,6 +130,21 @@ class Class_ extends PhpParser\BuilderAbstract
         return $this;
     }
 
+    /**
+     * Sets doc comment for the property.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return self The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = array(
+            'comments' => array($this->normalizeDocComment($docComment))
+        );
+
+        return $this;
+    }
+
     /**
      * Returns the built class node.
      *
@@ -138,6 +156,6 @@ class Class_ extends PhpParser\BuilderAbstract
             'extends' => $this->extends,
             'implements' => $this->implements,
             'stmts' => array_merge($this->uses, $this->constants, $this->properties, $this->methods),
-        ));
+        ), $this->attributes);
     }
 }

lib/PhpParser/Builder/Function_.php

@@ -13,6 +13,7 @@ class Function_ extends PhpParser\BuilderAbstract
     protected $returnByRef;
     protected $params;
     protected $stmts;
+    protected $attributes;
 
     /**
      * Creates a function builder.
@@ -25,6 +26,7 @@ class Function_ extends PhpParser\BuilderAbstract
         $this->returnByRef = false;
         $this->params = array();
         $this->stmts = array();
+        $this->attributes = array();
     }
 
     /**
@@ -100,6 +102,21 @@ class Function_ extends PhpParser\BuilderAbstract
         return $this;
     }
 
+    /**
+     * Sets doc comment for the function.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return self The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = array(
+            'comments' => array($this->normalizeDocComment($docComment))
+        );
+
+        return $this;
+    }
+
     /**
      * Returns the built function node.
      *
@@ -110,6 +127,6 @@ class Function_ extends PhpParser\BuilderAbstract
             'byRef'  => $this->returnByRef,
             'params' => $this->params,
             'stmts'  => $this->stmts,
-        ));
+        ), $this->attributes);
     }
 }

lib/PhpParser/Builder/Interface_.php

@@ -12,6 +12,7 @@ class Interface_ extends PhpParser\BuilderAbstract
     protected $extends;
     protected $constants;
     protected $methods;
+    protected $attributes;
 
     /**
      * Creates an interface builder.
@@ -22,6 +23,7 @@ class Interface_ extends PhpParser\BuilderAbstract
         $this->name = $name;
         $this->extends = array();
         $this->constants = $this->methods = array();
+        $this->attributes = array();
     }
 
     /**
@@ -84,6 +86,21 @@ class Interface_ extends PhpParser\BuilderAbstract
         return $this;
     }
 
+    /**
+     * Sets doc comment for the property.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return self The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = array(
+            'comments' => array($this->normalizeDocComment($docComment))
+        );
+
+        return $this;
+    }
+
     /**
      * Returns the built class node.
      *
@@ -93,6 +110,6 @@ class Interface_ extends PhpParser\BuilderAbstract
         return new Stmt\Interface_($this->name, array(
             'extends' => $this->extends,
             'stmts' => array_merge($this->constants, $this->methods),
-        ));
+        ), $this->attributes);
     }
 }

lib/PhpParser/Builder/Method.php

@@ -14,6 +14,7 @@ class Method extends PhpParser\BuilderAbstract
     protected $returnByRef;
     protected $params;
     protected $stmts;
+    protected $attributes;
 
     /**
      * Creates a method builder.
@@ -27,6 +28,7 @@ class Method extends PhpParser\BuilderAbstract
         $this->returnByRef = false;
         $this->params = array();
         $this->stmts = array();
+        $this->attributes = array();
     }
 
     /**
@@ -177,6 +179,21 @@ class Method extends PhpParser\BuilderAbstract
         return $this;
     }
 
+    /**
+     * Sets doc comment for the method.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return self The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = array(
+            'comments' => array($this->normalizeDocComment($docComment))
+        );
+
+        return $this;
+    }
+
     /**
      * Returns the built method node.
      *
@@ -188,6 +205,6 @@ class Method extends PhpParser\BuilderAbstract
             'byRef'  => $this->returnByRef,
             'params' => $this->params,
             'stmts'  => $this->stmts,
-        ));
+        ), $this->attributes);
     }
 }

lib/PhpParser/Builder/Property.php

@@ -11,6 +11,7 @@ class Property extends PhpParser\BuilderAbstract
 
     protected $type;
     protected $default;
+    protected $attributes;
 
     /**
      * Creates a property builder.
@@ -22,6 +23,7 @@ class Property extends PhpParser\BuilderAbstract
 
         $this->type = 0;
         $this->default = null;
+        $this->attributes = array();
     }
 
     /**
@@ -81,6 +83,21 @@ class Property extends PhpParser\BuilderAbstract
         return $this;
     }
 
+    /**
+     * Sets doc comment for the property.
+     *
+     * @param PhpParser\Comment\Doc|string $docComment Doc comment to set
+     *
+     * @return self The builder instance (for fluid interface)
+     */
+    public function setDocComment($docComment) {
+        $this->attributes = array(
+            'comments' => array($this->normalizeDocComment($docComment))
+        );
+
+        return $this;
+    }
+
     /**
      * Returns the built class node.
      *
@@ -91,7 +108,8 @@ class Property extends PhpParser\BuilderAbstract
             $this->type !== 0 ? $this->type : Stmt\Class_::MODIFIER_PUBLIC,
             array(
                 new Stmt\PropertyProperty($this->name, $this->default)
-            )
+            ),
+            $this->attributes
         );
     }
 }

lib/PhpParser/BuilderAbstract.php

@@ -6,6 +6,7 @@ use PhpParser\Node\Name;
 use PhpParser\Node\Expr;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Scalar;
+use PhpParser\Comment;
 
 abstract class BuilderAbstract implements Builder {
     /**
@@ -89,6 +90,23 @@ abstract class BuilderAbstract implements Builder {
         }
     }
 
+    /**
+     * Normalizes a doc comment: Converts plain strings to PhpParser\Comment\Doc.
+     *
+     * @param Comment\Doc|string $docComment The doc comment to normalize
+     *
+     * @return Comment\Doc The normalized doc comment
+     */
+    protected function normalizeDocComment($docComment) {
+        if ($docComment instanceof Comment\Doc) {
+            return $docComment;
+        } else if (is_string($docComment)) {
+            return new Comment\Doc($docComment);
+        } else {
+            throw new \LogicException('Doc comment must be a string or an instance of PhpParser\Comment\Doc');
+        }
+    }
+
     /**
      * Sets a modifier in the $this->type property.
      *

test/PhpParser/Builder/ClassTest.php

@@ -2,10 +2,10 @@
 
 namespace PhpParser\Builder;
 
+use PhpParser\Comment;
 use PhpParser\Node;
 use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
-use PhpParser\NodeVisitorAbstract;
 
 class ClassTest extends \PHPUnit_Framework_TestCase
 {
@@ -86,6 +86,39 @@ class ClassTest extends \PHPUnit_Framework_TestCase
         );
     }
 
+    public function testDocComment() {
+        $docComment = <<<'DOC'
+/**
+ * Test
+ */
+DOC;
+        $class = $this->createClassBuilder('Test')
+            ->setDocComment($docComment)
+            ->getNode();
+
+        $this->assertEquals(
+            new Stmt\Class_('Test', array(), array(
+                'comments' => array(
+                    new Comment\Doc($docComment)
+                )
+            )),
+            $class
+        );
+
+        $class = $this->createClassBuilder('Test')
+            ->setDocComment(new Comment\Doc($docComment))
+            ->getNode();
+
+        $this->assertEquals(
+            new Stmt\Class_('Test', array(), array(
+                'comments' => array(
+                    new Comment\Doc($docComment)
+                )
+            )),
+            $class
+        );
+    }
+
     /**
      * @expectedException \LogicException
      * @expectedExceptionMessage Unexpected node of type "Stmt_Echo"
@@ -95,4 +128,13 @@ class ClassTest extends \PHPUnit_Framework_TestCase
             ->addStmt(new Stmt\Echo_(array()))
         ;
     }
+
+    /**
+     * @expectedException \LogicException
+     * @expectedExceptionMessage Doc comment must be a string or an instance of PhpParser\Comment\Doc
+     */
+    public function testInvalidDocComment() {
+        $this->createClassBuilder('Test')
+            ->setDocComment(new Comment('Test'));
+    }
 }

test/PhpParser/Builder/FunctionTest.php

@@ -2,6 +2,7 @@
 
 namespace PhpParser\Builder;
 
+use PhpParser\Comment;
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Expr\Print_;
@@ -65,6 +66,16 @@ class FunctionTest extends \PHPUnit_Framework_TestCase
         );
     }
 
+    public function testDocComment() {
+        $node = $this->createFunctionBuilder('test')
+            ->setDocComment('/** Test */')
+            ->getNode();
+
+        $this->assertEquals(new Stmt\Function_('test', array(), array(
+            'comments' => array(new Comment\Doc('/** Test */'))
+        )), $node);
+    }
+
     /**
      * @expectedException \LogicException
      * @expectedExceptionMessage Expected parameter node, got "Name"

test/PhpParser/Builder/InterfaceTest.php

@@ -5,6 +5,7 @@ namespace PhpParser\Builder;
 use PhpParser\Node;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Scalar\DNumber;
+use PhpParser\Comment;
 
 class InterfaceTest extends \PHPUnit_Framework_TestCase
 {
@@ -67,6 +68,16 @@ class InterfaceTest extends \PHPUnit_Framework_TestCase
         $this->assertInstanceOf('PhpParser\Node\Stmt\ClassMethod', $contract->stmts[1]);
     }
 
+    public function testDocComment() {
+        $node = $this->builder
+            ->setDocComment('/** Test */')
+            ->getNode();
+
+        $this->assertEquals(new Stmt\Interface_('Contract', array(), array(
+            'comments' => array(new Comment\Doc('/** Test */'))
+        )), $node);
+    }
+
     /**
      * @expectedException \LogicException
      * @expectedExceptionMessage Unexpected node of type "Stmt_PropertyProperty"

test/PhpParser/Builder/MethodTest.php

@@ -6,6 +6,7 @@ use PhpParser\Node;
 use PhpParser\Node\Expr\Print_;
 use PhpParser\Node\Scalar\String;
 use PhpParser\Node\Stmt;
+use PhpParser\Comment;
 
 class MethodTest extends \PHPUnit_Framework_TestCase
 {
@@ -109,6 +110,15 @@ class MethodTest extends \PHPUnit_Framework_TestCase
             $node
         );
     }
+    public function testDocComment() {
+        $node = $this->createMethodBuilder('test')
+            ->setDocComment('/** Test */')
+            ->getNode();
+
+        $this->assertEquals(new Stmt\ClassMethod('test', array(), array(
+            'comments' => array(new Comment\Doc('/** Test */'))
+        )), $node);
+    }
 
     /**
      * @expectedException \LogicException

test/PhpParser/Builder/PropertyTest.php

@@ -6,6 +6,7 @@ use PhpParser\Node\Name;
 use PhpParser\Node\Stmt;
 use PhpParser\Node\Expr;
 use PhpParser\Node\Scalar;
+use PhpParser\Comment;
 
 class PropertyTest extends \PHPUnit_Framework_TestCase
 {
@@ -62,6 +63,22 @@ class PropertyTest extends \PHPUnit_Framework_TestCase
         );
     }
 
+    public function testDocComment() {
+        $node = $this->createPropertyBuilder('test')
+            ->setDocComment('/** Test */')
+            ->getNode();
+
+        $this->assertEquals(new Stmt\Property(
+            Stmt\Class_::MODIFIER_PUBLIC,
+            array(
+                new Stmt\PropertyProperty('test')
+            ),
+            array(
+                'comments' => array(new Comment\Doc('/** Test */'))
+            )
+        ), $node);
+    }
+
     /**
      * @dataProvider provideTestDefaultValues
      */