Przeglądaj źródła

Added see-tag and excluded sami-markdown from being rendered if cloned into a project and sample config is used.

Joachim M. Giæver 7 lat temu
rodzic
commit
87b7c1f0fd
3 zmienionych plików z 76 dodań i 12 usunięć
  1. 27 3
      README.md
  2. 44 9
      SamiTwigExtension.php
  3. 5 0
      example.conf.php

+ 27 - 3
README.md

@@ -64,7 +64,8 @@ $sami["twig"]->addExtension(new Markdown\SamiTwigExtension());
 |[short_description](#short_description-markdownsamitwigextension)|string ***v*** null|public static| Returns the short description of a reflection.|
 |[long_description](#long_description-markdownsamitwigextension)|string ***v*** null|public static| Returns a long description (both short and long) of a reflection.|
 |[deprecated](#deprecated-markdownsamitwigextension)|string ***v*** null|public static| Returnes a deprecated label if class, method etc is.|
-|[todo](#todo-markdownsamitwigextension)||public static| |
+|[todo](#todo-markdownsamitwigextension)|array ***v*** null|public static| Returns todo-tag for Reflection.|
+|[see](#see-markdownsamitwigextension)|array ***v*** null|public static| Returns see-tag for Reflection.|
 |[href](#href-markdownsamitwigextension)|string|public static| Returnes a markdown link.|
 |[toc](#toc-markdownsamitwigextension)|string|public static| Tabel of contents|
 |[param_hint](#param_hint-markdownsamitwigextension)|string|public static| Get hints of a param.|
@@ -168,12 +169,35 @@ Returns: string ***v*** null
 ```php
 public static function todo(Reflection $refl);
 ```
+ Returns todo-tag for Reflection.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|Reflection|$refl|Reflection to get todo tag from.|
+
+Returns: array ***v*** null
+
+---
+
+
+##### see `Markdown\SamiTwigExtension`
+```php
+public static function see(Reflection $refl);
+```
+ Returns see-tag for Reflection.
+
 
 Parameters
 
 | Type | Variable | Description |
 |---|---|---|
-|Reflection|$refl|*None*|
+|Reflection|$refl|Reflection to get see-tag from.|
+
+Returns: array ***v*** null
+
 ---
 
 
@@ -284,7 +308,7 @@ public static function method_hint(MethodReflection $method, bool $link = false)
 
 This hints is typically what a method returns, e.g `string`, `bool` etc.
 
-Method works similar as @see param_hint
+Method works similar as `param_hint`.
 
 
 Parameters

+ 44 - 9
SamiTwigExtension.php

@@ -43,7 +43,10 @@ use \Sami\Reflection\InterfaceReflection as InterfaceReflection;
  * $sami["twig"]->addExtension(new Markdown\SamiTwigExtension());
  * ```
  *
+ * @see Twig_Extension
+ * @see Sami
  * @see example.conf.php
+ *
  * @author Joachim M. Giaever (joachim[]giaever.org)
  * @version 0.1
  */
@@ -170,8 +173,24 @@ class SamiTwigExtension extends \Twig_Extension {
         );
     }
 
+    /** 
+     * Returns todo-tag for Reflection. 
+     * 
+     * @param Reflection $refl Reflection to get todo tag from.
+     * @return array|null Null on empty
+     */
     public static function todo(Reflection $refl) {
-        return (empty($todo = $refl->getTodo())) ? $todo : null;
+        return empty($todo = $refl->getTodo()) ? $todo : null;
+    }
+
+    /**
+     * Returns see-tag for Reflection.
+     *
+     * @param Reflection $refl Reflection to get see-tag from.
+     * @return array|null Null on empty
+     */
+    public static function see(Reflection $refl) {
+        return empty($see = $refl->getTags("see")) ? $see : null;
     }
 
     /**
@@ -343,8 +362,9 @@ class SamiTwigExtension extends \Twig_Extension {
      *
      * This hints is typically what a method returns, e.g `string`, `bool` etc.
      *
-     * Method works similar as @see param_hint
+     * Method works similar as `param_hint`.
      *
+     * @see self::param_hint
      * @param \Sami\Reflection\MethodReflection $method
      * @param bool $link = false
      * @return string
@@ -414,6 +434,7 @@ class SamiTwigExtension extends \Twig_Extension {
      * access function name(paramterers [= "value"]);
      * ```
      *
+     * @see param_hint
      * @param \Sami\Reflection\MethodReflection $method Method reflection
      * @param bool $incname Adds default parameter values on true
      * @return string
@@ -573,17 +594,24 @@ class SamiTwigExtension extends \Twig_Extension {
 
         // Create descriptions
         foreach ($methods as $method) {
-            $details[] = sprintf("\n##### %s `%s`\n```php\n%s function %s\n```%s%s%s%s%s%s\n---\n",
+            $details[] = sprintf("\n##### %s `%s`\n```php\n%s function %s\n```%s%s%s%s%s%s%s\n---\n",
                 $method->getName(), $method->getClass()->getName(),
                 self::method_access($method),
                 self::method_signature($method),
+                (function() use ($method) {
+                    if (!empty($see = self::see($method))) {
+                        return "\nSee also:\n* " . self::join($see, "* ") . "\n";
+                    }
+
+                    return null;
+                })(),
 
                 // Method description, padded left with > (block/indent)
                 (function() use ($method) {
-                    if (empty(self::long_description($method)))
-                        return null;
+                    if (!empty($desc = self::long_description($method)))
+                        return "\n " . $desc . "\n";
 
-                    return "\n " . self::long_description($method) . "\n";
+                    return null;
                 })(),
 
                 // TODO: Debug this. No output?
@@ -624,11 +652,11 @@ class SamiTwigExtension extends \Twig_Extension {
                         return null;
 
                     // Return exceptions padded whith > and linked to...
-                    return "\n> Throws: " . (function() use ($method) {
+                    return "\nThrows: " . (function() use ($method) {
                         $links = array();
                         foreach($method->getExceptions() as $Exception)
                             $links[] = self::href($Exception[0]->getShortName(), $Exception[0]->getName(), false, "Exception: " . $Exception[0]->getName());
-                        return "\n> * " . join("\n> * ", $links) . "\n";
+                        return "\n* " . self::join($links, "* ") . "\n";
                     })();
                 })(),
 
@@ -663,7 +691,7 @@ class SamiTwigExtension extends \Twig_Extension {
     public static function render_class(ClassReflection $class) {
 
         return sprintf(
-            "\n### %s `%s`\n%s%s%s",
+            "\n### %s `%s`\n%s%s%s%s",
             $class->getShortName(),
             $class->getNamespace(),
             
@@ -716,6 +744,13 @@ class SamiTwigExtension extends \Twig_Extension {
                 return "\n" . self::long_description($class) . "\n";
             })(),
 
+            (function() use ($class) {
+                if (!empty($see = self::see($class)))
+                    return "\nAlso see:\n* " . self::join($see, "* ") . "\n";
+
+                return null;
+            })(),
+
             self::render_methods($class->getMethods())
         );
     }

+ 5 - 0
example.conf.php

@@ -15,6 +15,11 @@ require "SamiTwigExtension.php";
 
 $iterator = Finder::create()
     ->files()
+    /**
+     * For those who clone this into their project,
+     * we'll exclude sami-markdown to be rendered.
+     */
+    ->exclude("sami-markdown")
     ->name('*.php')
     ->in($dir = './')
 ;