detailed page template update

src/Doc/Business/DocBlock.php

@@ -88,21 +88,21 @@ class DocBlock {
                     continue;
                 }else {
                     // get the name of the param
-                    preg_match('/@(\w+)/', $info, $matches);
-                    $param_name = $matches[1];
+                    if (preg_match('/@param +\\$([^ ]+) +([^ ]+) +(.*)$/', $info, $matches) == 1) {
+                        $param_name = $matches[1];
+                        $param_type = $matches[2];
+                        $value = $matches[3];
 
-                    // remove the param from the string
-                    $value = str_replace("@$param_name ", '', $info);
 
-                    // if the param hasn't been added yet, create a key for it
-                    if( !isset($this->all_params[$param_name]) ) {
-                        $this->all_params[$param_name] = array();
-                    }
-
-                    // push the param value into place
-                    $this->all_params[$param_name][] = $value;
+                        // push the param value into place
+                        $this->all_params[$param_name] = [
+                            "name" => $param_name,
+                            "param_type" => $param_type,
+                            "description" => $value
+                        ];
 
-                    continue;
+                        continue;
+                    }
                 }
             }
         }

src/Doc/Business/LuDocBusiness.php

@@ -3,181 +3,108 @@
  * Created by PhpStorm.
  * User: robin
  * Date: 10/22/15
- * Time: 8:24 PM
+ * Time: 9:59 PM
  */
 
 namespace Luticate\Doc\Business;
 
-use Luticate\Utils\LuRoute;
-use Luticate\Utils\LuRouteDbo;
-use ReflectionMethod;
-use Twig_Environment;
-use Twig_Loader_Filesystem;
+use Exception;
 
-class LuDocBusiness
-{
-    /**
-     * @param $prefix string
-     */
-    public static function setupRoutes($prefix = "/luticate")
-    {
-        $ns = 'Luticate\Doc\Business\\';
-
-        $route = LuRoute::getInstance();
-        $route->get("$prefix/doc", "${ns}LuDocBusiness", "index");
-        $route->get("$prefix/doc/{businessHyphen}/{method}", "${ns}LuDocBusiness", "method");
-    }
+class DocBlock {
 
-    private static function getBusinesses()
-    {
-        $route = LuRoute::getInstance();
-
-        $businesses = [];
-        foreach ($route->getRoutes() as $r) {
-
-            if (!isset($businesses[$r->getBusinessClass()])) {
-                $businesses[$r->getBusinessClass()] = [];
-            }
-            $businesses[$r->getBusinessClass()][] = $r;
-        }
-        return $businesses;
-    }
+    public $docblock,
+        $description = null,
+        $all_params = array();
 
     /**
-     * @param $business string
-     * @return string
+     * Parses a docblock;
      */
-    private static function getBusinessName($business)
-    {
-        $tab = explode("\\", $business);
-        return array_pop($tab);
-    }
+    function __construct($docblock) {
+        if( !is_string($docblock) ) {
+            throw new Exception("DocBlock expects first parameter to be a string");
+        }
 
-    /**
-     * @param $business string
-     * @return string
-     */
-    private static function getBusinessHyphen($business)
-    {
-        return str_replace("\\", "-", $business);
+        $this->docblock = $docblock;
+        $this->parse_block();
     }
 
     /**
-     * @param $business string
-     * @return string
+     * An alias to __call();
+     * allows a better DSL
+     *
+     * @param string $param_name
+     * @return mixed
      */
-    private static function getBusinessFromHyphen($business)
-    {
-        return str_replace("-", "\\", $business);
-    }
-
-    private static function printTwig($file, $vars)
-    {
-        $loader = new Twig_Loader_Filesystem(__DIR__ . "/../Templates");
-        $twig = new Twig_Environment($loader, array());
-        $template = $twig->loadTemplate($file . ".twig");
-        $content = $template->render($vars);
-        echo $content;
-        exit;
+    public function __get($param_name) {
+        return $this->$param_name();
     }
 
     /**
-     * Print the help page
+     * Checks if the param exists
+     *
+     * @param string $param_name
+     * @return mixed
      */
-    public static function index()
-    {
-        $businesses_ = self::getBusinesses();
-        /**
-         * @var $businesses LuRouteDbo[]
-         */
-        $businesses_tiwg = [];
-        foreach ($businesses_ as $businesses) {
-            $businessHyphen = self::getBusinessHyphen($businesses[0]->getBusinessClass());
-            $businessName = self::getBusinessName($businesses[0]->getBusinessClass());
-            $business_tiwg = [];
-            $business_tiwg["name"] = $businessName;
-            $business_tiwg["name_hyphen"] = $businessHyphen;
-            $business_tiwg["routes"] = [];
-
-            foreach ($businesses as $business) {
-                $reflection = new ReflectionMethod($business->getBusinessClass(), $business->getBusinessMethod());
-                $description = $reflection->getDocComment();
-                if ($description === false) {
-                    $description = "No description available";
-                }
-                else {
-                    $docParser = new DocBlock($description);
-                    $description = $docParser->description;
-                }
-                $business_tiwg["routes"][] = [
-                    "method" => $business->getMethod(),
-                    "url" => $business->getUrl(),
-                    "businessMethod" => $business->getBusinessMethod(),
-                    "description" => $description
-                ];
+    public function __call($param_name, $values = null) {
+        if( $param_name == "description" ) {
+            return $this->description;
+        }else if( isset($this->all_params[$param_name]) ) {
+            $params = $this->all_params[$param_name];
+
+            if( count($params) == 1 ) {
+                return $params[0];
+            }else {
+                return $params;
             }
-            $businesses_tiwg[] = $business_tiwg;
         }
 
-        self::printTwig("index.html", array("businesses" => $businesses_tiwg));
+        return null;
     }
 
     /**
-     * Print the help page for the selected business method.
-     * The business must have the full namespace, hyphen separated
-     * eg: App-Http-Business-MyBusinessClass
-     * @param $businessHyphen string The business to print help
-     * @param $method string The method to print help
+     * Parse each line in the docblock
+     * and store the params in `$this->all_params`
+     * and the rest in `$this->description`
      */
-    public static function method($businessHyphen, $method)
-    {
-        $businesses_ = self::getBusinesses();
-        $businessName = self::getBusinessFromHyphen($businessHyphen);
-        /**
-         * @var $businesses LuRouteDbo[]
-         */
-        $businesses = $businesses_[$businessName];
-        $business = null;
-        foreach ($businesses as $b) {
-            if ($b->getBusinessMethod() == $method) {
-                $business = $b;
-            }
-        }
-
-        $reflection = new ReflectionMethod($business->getBusinessClass(), $business->getBusinessMethod());
-        $description = $reflection->getDocComment();
-        $docParser = null;
-        if ($description === false) {
-            $description = "No description available";
-        }
-        else {
-            $docParser = new DocBlock($description);
-            $description = $docParser->description;
-        }
-
-        $parameters = [];
-        foreach ($reflection->getParameters() as $param) {
-            $p = [];
-
-            $p["name"] = $param->getName();
-            if (!is_null($docParser) && isset($docParser->all_params[$param->getName()])) {
-                $p["description"] = $docParser->all_params[$param->getName()];
-                $p["type"] = "Unknown";
-                $p["annotations"] = "";
-            }
-            else {
-                $p["description"] = $description;
-                $p["type"] = "Unknown";
-                $p["annotations"] = "";
+    private function parse_block() {
+        // split at each line
+        foreach(preg_split("/(\r?\n)/", $this->docblock) as $line){
+
+            // if starts with an asterisk
+            if( preg_match('/^(?=\s+?\*[^\/])(.+)/', $line, $matches) ) {
+
+                $info = $matches[1];
+
+                // remove wrapping whitespace
+                $info = trim($info);
+
+                // remove leading asterisk
+                $info = preg_replace('/^(\*\s+?)/', '', $info);
+
+                // if it doesn't start with an "@" symbol
+                // then add to the description
+                if( $info[0] !== "@" ) {
+                    $this->description .= "\n$info";
+                    continue;
+                }else {
+                    // get the name of the param
+                    if (preg_match('/@param +\\$([^ ]+) +([^ ]+) +(.*)$/', $info, $matches) == 1) {
+                        $param_name = $matches[1];
+                        $param_type = $matches[2];
+                        $value = $matches[3];
+
+
+                        // push the param value into place
+                        $this->all_params[$param_name] = [
+                            "name" => $param_name,
+                            "type" => $param_type,
+                            "description" => $value
+                        ];
+
+                        continue;
+                    }
+                }
             }
-
-            $parameters[] = $p;
         }
-
-        self::printTwig("method.html", array(
-            "description" => str_replace("\n", "<br />", $description),
-            "url" => $business->getUrl(),
-            "method" => $business->getMethod(),
-            "parameters" => $parameters));
     }
 }

src/Doc/Templates/method.html.twig

@@ -155,7 +155,7 @@
     <section class="content-wrapper main-content clear-fix">
 
         <h1>{{ method }} {{ url }}</h1>
-        <p>{{ description }}</p>
+        <p>{{ description | raw }}</p>
         <h3>Parameters</h3>
 
         <table class="help-page-table">
@@ -167,7 +167,7 @@
             <tr>
                 <td class="parameter-name">{{ param.name }}</td>
                 <td class="parameter-documentation">
-                    <p>{{ param.description }}</p>
+                    <p>{{ param.description | raw }}</p>
                 </td>
                 <td class="parameter-type">
                     {{ param.type }}