Added comments

Author: dantleech

AutoRoute/AutoRouteMaker.php

@@ -6,6 +6,9 @@
 use Symfony\Cmf\Bundle\RoutingAutoBundle\Document\AutoRoute;
 
 /**
+ * This class is responsible for creating and updating the actual
+ * AutoRoute documents.
+ *
  * @author Daniel Leech <[email protected]>
  */
 class AutoRouteMaker

AutoRoute/AutoRouteStack.php

@@ -26,6 +26,11 @@ public function close()
 
     public function addRoute($route)
     {
+        // note that we can't type hint here as this method is overridden.
+        if (!$route instanceof AutoRoute) {
+            throw new \BadMethodCallException('You must pass an AutoRoute document to addRoute');
+        }
+
         parent::addRoute($route);
     }
 }

AutoRoute/BuilderContext.php

@@ -5,6 +5,13 @@
 use Symfony\Cmf\Bundle\RoutingExtraBundle\Document\Route;
 
 /**
+ * This class might better be called AutoRouteRequest.
+ * It holds all the RouteStack objects and the content document.
+ *
+ * All data needed to create the auto route is contained in this
+ * class and everything involved in the route building process has
+ * access to this class.
+ *
  * @author Daniel Leech <[email protected]>
  */
 class BuilderContext
@@ -13,6 +20,12 @@ class BuilderContext
     protected $stagedRouteStack;
     protected $content;
 
+    /**
+     * Return an ordered array of all routes from
+     * all stacks.
+     *
+     * @return array
+     */
     public function getRoutes()
     {
         $routes = array();
@@ -23,11 +36,20 @@ public function getRoutes()
         return $routes;
     }
 
+    /**
+     * Stage a route stack. TBH this is probably not
+     * required now. Could probably be replaced simply
+     * with addRouteStack.
+     */
     public function stageRouteStack(RouteStack $routeStack)
     {
         $this->stagedRouteStack = $routeStack;
     }
 
+    /**
+     * As with above. This can probably be replaced with something 
+     * simpler.
+     */
     public function commitRouteStack()
     {
         if (null === $this->stagedRouteStack) {
@@ -47,17 +69,36 @@ public function commitRouteStack()
         $this->stagedRouteStack = null;
     }
 
+    /**
+     * Return all route stacks.
+     *
+     * @return array
+     */
     public function getRouteStacks()
     {
         return $this->routeStacks;
     }
 
+    /**
+     * Return the "top" route (last added) in
+     * the stack.
+     *
+     * @return object
+     */
     public function getTopRoute()
     {
         $routes = $this->getRoutes();
         return end($routes);
     }
 
+    /**
+     * Returns the complete path as determined
+     * by the route stacks.
+     *
+     * Note that this path is not absolute.
+     *
+     * @return string
+     */
     public function getFullPath()
     {
         $paths = array();
@@ -71,11 +112,21 @@ public function getFullPath()
 
     }
 
+    /**
+     * Set the content object (e.g. a blog post)
+     *
+     * @param object
+     */
     public function setContent($content)
     {
         $this->content = $content;
     }
 
+    /**
+     * Returns the content object (e.g. a blog post)
+     *
+     * @return object
+     */
     public function getContent()
     {
         return $this->content;

AutoRoute/Factory.php

@@ -33,12 +33,27 @@ public function __construct(ContainerInterface $container, Builder $builder)
         $this->builder = $builder;
     }
 
+    /**
+     * Register an auto route mapping for the given class.
+     *
+     * @param string $classFqn Class to map
+     * @param array  $mapping  Mapping configuration
+     */
     public function registerMapping($classFqn, $mapping)
     {
         $this->validateMapping($classFqn, $mapping);
         $this->mapping[$classFqn] = $mapping;
     }
 
+    /**
+     * Register an alias for a service ID of the specified type.
+     *
+     * e.g. registerAlias('path_provider', 'specified', 'symfony_cmf_[...]');
+     *
+     * @param string $type
+     * @param string $alias
+     * @param string $id
+     */
     public function registerAlias($type, $alias, $id)
     {
         if (!isset($this->serviceIds[$type])) {
@@ -48,6 +63,16 @@ public function registerAlias($type, $alias, $id)
         $this->serviceIds[$type][$alias] = $id;
     }
 
+    /**
+     * Creates the route stack builder chain for the given class FQN.
+     *
+     * The RouteStackBuilderUnitChain will provide all the route components
+     * for the content path.
+     *
+     * Note that we cache it.
+     *
+     * @return RouteStackBuilderUnitChain
+     */
     public function getRouteStackBuilderUnitChain($classFqn)
     {
         if (!isset($this->routeStackChains[$classFqn])) {
@@ -57,6 +82,14 @@ public function getRouteStackBuilderUnitChain($classFqn)
         return $this->routeStackChains[$classFqn];
     }
 
+    /**
+     * Return the build unit which will generate the content name
+     * route for the given class FQN.
+     *
+     * @param string $classFqn
+     *
+     * @return BuilderUnit
+     */
     public function getContentNameBuilderUnit($classFqn)
     {
         if (!isset($this->contentNameBuilderUnits[$classFqn])) {
@@ -69,6 +102,13 @@ public function getContentNameBuilderUnit($classFqn)
         return $this->contentNameBuilderUnits[$classFqn];
     }
 
+    /**
+     * Return true if the given class FQN is mapped.
+     *
+     * @param string $classFqn
+     *
+     * @return boolean
+     */
     public function hasMapping($classFqn)
     {
         // @todo: Do we need to support inheritance?

AutoRoute/PathActionInterface.php

@@ -5,14 +5,28 @@
 use Symfony\Cmf\Bundle\RoutingExtraBundle\Document\Route;
 
 /**
+ * The job of classes implementing this interface is to add
+ * a Route for each path element in the given RouteStack.
+ *
+ * The two scenarios are path "exists" and path "not_exists""
+ *
  * @author Daniel Leech <[email protected]>
  */
 interface PathActionInterface
 {
     /**
      * Initialize with config options
+     *
+     * @param array $options
      */
     public function init(array $options);
 
+    /**
+     * Perform the action. When the method has finished the
+     * RouteStack should contain an equal number of routes and
+     * path elements.
+     *
+     * @param RouteStack $stack
+     */
     public function execute(RouteStack $stack);
 }

AutoRoute/PathProviderInterface.php

@@ -3,6 +3,9 @@
 namespace Symfony\Cmf\Bundle\RoutingAutoBundle\AutoRoute;
 
 /**
+ * Classes implementing this interface add path elements
+ * to the RouteStack which are later resolved to routes.
+ *
  * @author Daniel Leech <[email protected]>
  */
 interface PathProviderInterface
@@ -13,7 +16,7 @@ interface PathProviderInterface
     public function init(array $options);
 
     /**
-     * Provide a URL
+     * Add path elements to the route stack
      *
      * @return string
      */