Docblocks, minor cleanups

src/CodeGenerationUtils/Autoloader/AutoloaderInterface.php

@@ -19,7 +19,7 @@
 namespace CodeGenerationUtils\Autoloader;
 
 /**
- * Basic autoloader utilities required to work with proxy files
+ * Basic autoloader utilities required to work with generated classes
  *
  * @author Marco Pivetta <ocramius@gmail.com>
  * @license MIT

src/CodeGenerationUtils/FileLocator/FileLocatorInterface.php

@@ -19,7 +19,7 @@
 namespace CodeGenerationUtils\FileLocator;
 
 /**
- * Basic autoloader utilities required to work with proxy files
+ * File locator - enables discovering files where generated classes are located
  *
  * @author Marco Pivetta <ocramius@gmail.com>
  * @license MIT

src/CodeGenerationUtils/Inflector/ClassNameInflectorInterface.php

@@ -19,7 +19,7 @@
 namespace CodeGenerationUtils\Inflector;
 
 /**
- * Interface for a proxy- to user-class and user- to proxy-class name inflector
+ * Interface for a proxy- to user- class and user- to proxy- class name inflector
  *
  * @author Marco Pivetta <ocramius@gmail.com>
  * @license MIT

src/CodeGenerationUtils/ReflectionBuilder/ClassBuilder.php

@@ -1,10 +1,27 @@
 <?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license.
+ */
 
 namespace CodeGenerationUtils\ReflectionBuilder;
 
 use PHPParser_Builder_Method;
 use PHPParser_Builder_Param;
 use PHPParser_Builder_Property;
+use PHPParser_BuilderAbstract;
 use PHPParser_Node;
 use PHPParser_Node_Const;
 use PHPParser_Node_Expr_ConstFetch;
@@ -17,7 +34,15 @@
 use ReflectionParameter;
 use ReflectionProperty;
 
-class ClassBuilder extends \PHPParser_BuilderAbstract
+/**
+ * Rudimentary utility to build an AST from a reflection class
+ *
+ * @todo should be splitted into various utilities like this one and eventually replace `Zend\Code\Generator`
+ *
+ * @author Marco Pivetta <ocramius@gmail.com>
+ * @license MIT
+ */
+class ClassBuilder extends PHPParser_BuilderAbstract
 {
     /**
      * @param \ReflectionClass $reflectionClass

src/CodeGenerationUtils/Visitor/ClassClonerVisitor.php

@@ -1,4 +1,20 @@
 <?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license.
+ */
 
 namespace CodeGenerationUtils\Visitor;
 
@@ -8,6 +24,15 @@
 use PHPParser_Parser;
 use ReflectionClass;
 
+/**
+ * Visitor capable of generating an AST given a reflection class that is written in a file
+ *
+ * @todo doesn't work with evaluated code (file must exist)
+ * @todo simply skips if the AST is not empty - should instead be extended to decide what to do
+ *
+ * @author Marco Pivetta <ocramius@gmail.com>
+ * @license MIT
+ */
 class ClassClonerVisitor extends PHPParser_NodeVisitorAbstract
 {
     /**
@@ -24,17 +49,22 @@ public function __construct(ReflectionClass $reflectedClass)
 
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param array $nodes
+     *
+     * @return \PHPParser_Node[]
+     */
     public function beforeTraverse(array $nodes)
     {
-        // quickfix - if the list is empty, parse it
+        // quickfix - if the list is empty, replace it it
         if (empty($nodes)) {
             $parser = new PHPParser_Parser(new PHPParser_Lexer_Emulative);
 
             return $parser->parse(file_get_contents($this->reflectedClass->getFileName()));
         }
 
-        // @todo should instead decide what to do if the AST is not empty - maybe append the class in the end?
-
         return $nodes;
     }
 }

src/CodeGenerationUtils/Visitor/ClassExtensionVisitor.php

@@ -1,4 +1,20 @@
 <?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license.
+ */
 
 namespace CodeGenerationUtils\Visitor;
 
@@ -8,23 +24,56 @@
 use PHPParser_Node_Stmt_Namespace;
 use PHPParser_NodeVisitorAbstract;
 
+/**
+ * Visitor that extends the matched class in the visited AST from another given class
+ *
+ * @author Marco Pivetta <ocramius@gmail.com>
+ * @license MIT
+ */
 class ClassExtensionVisitor extends PHPParser_NodeVisitorAbstract
 {
+    /**
+     * @var string
+     */
     private $matchedClassFQCN;
+
+    /**
+     * @var string
+     */
     private $newParentClassFQCN;
+
+    /**
+     * @var \PHPParser_Node_Stmt_Namespace|null
+     */
     private $currentNamespace;
 
+    /**
+     * @param string $matchedClassFQCN
+     * @param string $newParentClassFQCN
+     */
     public function __construct($matchedClassFQCN, $newParentClassFQCN)
     {
         $this->matchedClassFQCN = (string) $matchedClassFQCN;
         $this->newParentClassFQCN = (string) $newParentClassFQCN;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * Cleans up internal state
+     *
+     * @param array $nodes
+     */
     public function beforeTraverse(array $nodes)
     {
         $this->currentNamespace = null;
     }
 
+    /**
+     * @param PHPParser_Node $node
+     *
+     * @return PHPParser_Node_Stmt_Namespace|null
+     */
     public function enterNode(PHPParser_Node $node)
     {
         if ($node instanceof PHPParser_Node_Stmt_Namespace) {
@@ -34,8 +83,18 @@ public function enterNode(PHPParser_Node $node)
         }
     }
 
-    // @todo this logic is basically a transformation applied on a filtered node
-    // @todo it can be abstracted away into a visitor that allows to modify the node via a callback
+    /**
+     * {@inheritDoc}
+     *
+     * When leaving a node that is a class, replaces it with a modified version that extends the
+     * given parent class
+     *
+     * @todo can be abstracted away into a visitor that allows to modify the node via a callback
+     *
+     * @param PHPParser_Node $node
+     *
+     * @return PHPParser_Node_Stmt_Class|void
+     */
     public function leaveNode(PHPParser_Node $node)
     {
         if ($node instanceof PHPParser_Node_Stmt_Namespace) {

src/CodeGenerationUtils/Visitor/ClassFQCNResolverVisitor.php

@@ -1,4 +1,20 @@
 <?php
+/*
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * This software consists of voluntary contributions made by many individuals
+ * and is licensed under the MIT license.
+ */
 
 namespace CodeGenerationUtils\Visitor;
 
@@ -9,6 +25,13 @@
 use PHPParser_NodeVisitorAbstract;
 use PHPParser_Parser;
 
+/**
+ * Resolves the FQCN of the class included in the AST.
+ * Assumes a single class.
+ *
+ * @author Marco Pivetta <ocramius@gmail.com>
+ * @license MIT
+ */
 class ClassFQCNResolverVisitor extends PHPParser_NodeVisitorAbstract
 {
     /**
@@ -21,17 +44,27 @@ class ClassFQCNResolverVisitor extends PHPParser_NodeVisitorAbstract
      */
     private $class;
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param array $nodes
+     */
     public function beforeTraverse(array $nodes)
     {
         $this->namespace = null;
         $this->class     = null;
     }
 
+    /**
+     * @param PHPParser_Node $node
+     *
+     * @throws Exception\UnexpectedValueException if more than one class is found
+     */
     public function enterNode(PHPParser_Node $node)
     {
         if ($node instanceof PHPParser_Node_Stmt_Namespace) {
             if ($this->namespace) {
-                throw new UnexpectedValueException('Multiple namespaces discovered');
+                throw new UnexpectedValueException('Multiple nested namespaces discovered (invalid AST?)');
             }
 
             $this->namespace = $node;
@@ -47,9 +80,9 @@ public function enterNode(PHPParser_Node $node)
     }
 
     /**
-     * @return string
+     * @return string the short name of the discovered class
      *
-     * @throws Exception\UnexpectedValueException in case no class could be resolved
+     * @throws Exception\UnexpectedValueException if no class could be resolved
      */
     public function getName()
     {
@@ -61,7 +94,7 @@ public function getName()
     }
 
     /**
-     * @return string
+     * @return string the namespace name of the discovered class
      */
     public function getNamespace()
     {