|
|
@@ -0,0 +1,865 @@
|
|
|
+<?php namespace Markdown;
|
|
|
+
|
|
|
+use \Sami\Reflection\Reflection as Reflection;
|
|
|
+use \Sami\Reflection\ClassReflection as ClassReflection;
|
|
|
+use \Sami\Reflection\MethodReflection as MethodReflection;
|
|
|
+use \Sami\Reflection\ParameterReflection as ParameterReflection;
|
|
|
+use \Sami\Reflection\HintReflection as HintReflection;
|
|
|
+use \Sami\Reflection\InterfaceReflection as InterfaceReflection;
|
|
|
+
|
|
|
+/**
|
|
|
+ * An extension than builds a single ReadMe markdown
|
|
|
+ * file out of your code.
|
|
|
+ *
|
|
|
+ * By now, most is done "behind the scene" and the template
|
|
|
+ * is very minimal. This means that it's not much you can do to
|
|
|
+ * change any of the layout etc, without editing the actual code/class,
|
|
|
+ * but you may want to change template structure by calling
|
|
|
+ * the methods "render_classes", "render_class" etc, but be aware
|
|
|
+ * that these methods does not remove whitespaces and takes care of
|
|
|
+ * any format issues your template will get.
|
|
|
+ *
|
|
|
+ *
|
|
|
+ * This is in lack of a a single-file-documentation, for a project,
|
|
|
+ * and since the markdown language is very strict on format -
|
|
|
+ * (indentation, signs etc.) - using the twig template was a hassle,
|
|
|
+ * whitout ending with several "twig-files" that was unreadable (no
|
|
|
+ * indentation etc).
|
|
|
+ *
|
|
|
+ * Get [Sami](https://github.com/FriendsOfPHP/Sami/) and fork this
|
|
|
+ * repo
|
|
|
+ *
|
|
|
+ * ```bash
|
|
|
+ * git clone giaever@git.giaever.org:joachimmg/sami-markdown.git
|
|
|
+ * ```
|
|
|
+ *
|
|
|
+ * Include the `SamiTwigExtension.php` into your Sami configuration-file
|
|
|
+ * and add it to twig. See `example.conf.php` or
|
|
|
+ *
|
|
|
+ * * set template: `"template" => "markdown"`
|
|
|
+ * * add extension:
|
|
|
+ *
|
|
|
+ * ```php
|
|
|
+ * $sami["twig"]->addExtension(new Markdown\SamiTwigExtension());
|
|
|
+ * ```
|
|
|
+ *
|
|
|
+ * @see example.conf.php
|
|
|
+ * @author Joachim M. Giaever (joachim[]giaever.org)
|
|
|
+ * @version 0.1
|
|
|
+ */
|
|
|
+class SamiTwigExtension extends \Twig_Extension {
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Setting pretty-print to true will print
|
|
|
+ * tables in the read me into a pretty printet format,
|
|
|
+ * which makes it easier to read.
|
|
|
+ *
|
|
|
+ * @static
|
|
|
+ * @access public
|
|
|
+ */
|
|
|
+ public static $pretty_print = false;
|
|
|
+
|
|
|
+ /**
|
|
|
+ * @see $pretty_print
|
|
|
+ */
|
|
|
+ public function __construct(bool $pretty_print = false) {
|
|
|
+ self::$pretty_print = $pretty_print;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Set the functions available for the template engine.
|
|
|
+ * @return
|
|
|
+ */
|
|
|
+ public function getFunctions() {
|
|
|
+ return array(
|
|
|
+ new \Twig_Function("toc", array($this, "toc")),
|
|
|
+ new \Twig_Function("render", array($this, "render"))
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Checks if var is a Sami-reflection type.
|
|
|
+ *
|
|
|
+ * Makes it easier to determine if the variable is
|
|
|
+ * a string (namespace) or a Reflection-type.
|
|
|
+ *
|
|
|
+ * @param $var
|
|
|
+ * @return bool
|
|
|
+ */
|
|
|
+ private static function isReflection($var) {
|
|
|
+ return $var instanceof Reflection || $var instanceof HintReflection;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Join an array into a string.
|
|
|
+ *
|
|
|
+ * @param array $arr The array to join
|
|
|
+ * @param string $pad Padding letter (typically a asterisk etc)
|
|
|
+ * @param string $sep Separator, before the padding
|
|
|
+ * @param string $esep Ending separator
|
|
|
+ * @param string $epad Ending pad
|
|
|
+ * @return null On empty array
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ private static function join(array $arr, string $pad = "", string $sep = "\n", string $esep = "", string $epad = "") {
|
|
|
+ if (empty($arr))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ return $sep . $pad . join($sep . $pad, $arr) . $esep . $epad;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Returns x numbers of tabulations.
|
|
|
+ *
|
|
|
+ * @param int $depth
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ private static function tab(int $depth) {
|
|
|
+ return str_repeat("\t", $depth);
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Returns the short description of a reflection.
|
|
|
+ *
|
|
|
+ * @todo Implement $max
|
|
|
+ * @param \Sami\Reflection\Reflection $refl Reflection to return description of
|
|
|
+ * @param bool $oneliner Removes every newline and tabulation.
|
|
|
+ * @param int $max Maximum of letters
|
|
|
+ * @return string|null Null on empty
|
|
|
+ */
|
|
|
+ public static function short_description(Reflection $refl, bool $oneliner = true, int $max = -1) {
|
|
|
+ return !empty($desc = $refl->getShortDesc()) ? (
|
|
|
+ $oneliner ? str_replace(array("\n", "\r", "\t"), "", $desc) : $desc
|
|
|
+ ) : null;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Returns a long description (both short and long) of a reflection.
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\Reflection $refl Reflection to return description of
|
|
|
+ * @param bool $oneliner Removes every newline and tabulation
|
|
|
+ * @return string|null Null on empty
|
|
|
+ */
|
|
|
+ public static function long_description(Reflection $refl, bool $oneliner = false) {
|
|
|
+ return !empty($desc = self::short_description($refl, false) . (!empty($refl->getLongDesc()) ? "\n\n" . $refl->getLongDesc() : null)) ? (
|
|
|
+ $oneliner ? str_replace(array("\n", "\r", "\t"), "", $desc) : $desc
|
|
|
+ ) : null;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Returnes a deprecated label if class, method etc is.
|
|
|
+ *
|
|
|
+ * If `$notice` is false, it will include the deprecated
|
|
|
+ * note - if given in the documentation.
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\Reflection Reflection
|
|
|
+ * @param bool $notice Just as notice
|
|
|
+ * @return string|null Null on none
|
|
|
+ */
|
|
|
+ public static function deprecated(Reflection $refl, $notice = true) {
|
|
|
+
|
|
|
+ if (empty($refl->getDeprecated()))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ if ($notice)
|
|
|
+ return "`@deprecated`";
|
|
|
+
|
|
|
+ return sprintf(
|
|
|
+ "`@deprecated`: %s",
|
|
|
+ join(" ", $refl->getDeprecated()[0])
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ public static function todo(Reflection $refl) {
|
|
|
+ return (empty($todo = $refl->getTodo())) ? $todo : null;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Returnes a markdown link.
|
|
|
+ *
|
|
|
+ * To match the markdown template classes is linked to by
|
|
|
+ * `#classname-namespace`, and methods `#method-namespace\classname`
|
|
|
+ * and namespaces is linked to by `#namespace`, `$namespace` must be set
|
|
|
+ * to true when linking to it.
|
|
|
+ *
|
|
|
+ * @param string $ltxt The link text
|
|
|
+ * @param string $lurl The link destination
|
|
|
+ * @param bool $namespace True when linking to a namespace
|
|
|
+ * @param string $desc Link title (like the html title/hover-tag)
|
|
|
+ * @return string
|
|
|
+ **/
|
|
|
+ public static function href(string $ltxt, string $lurl, bool $namespace = false, string $desc = null) {
|
|
|
+ $desc = $desc ? sprintf(' "%s"', $desc) : null;
|
|
|
+
|
|
|
+ // Not linking a namespace directly
|
|
|
+ if (!$namespace) {
|
|
|
+ // Not within this package
|
|
|
+ if (strpos($lurl, "\\") === false)
|
|
|
+ return sprintf("[%s](https://www.google.no/search?q=%s%s)", $ltxt, rawurlencode($lurl), $desc);
|
|
|
+ else // Withing package; set `name`-`namespace` order
|
|
|
+ $lurl = sprintf(
|
|
|
+ "%s %s",
|
|
|
+ substr($lurl, strrpos($lurl, "\\")),
|
|
|
+ substr($lurl, 0, strrpos($lurl, "\\", 1))
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ return sprintf(
|
|
|
+ "[%s](#%s%s)",
|
|
|
+ $ltxt,
|
|
|
+ strtolower(
|
|
|
+ str_replace(
|
|
|
+ array("\\", " "), // Replace "\" = "" and " " = "-"
|
|
|
+ array("", "-"),
|
|
|
+ $lurl
|
|
|
+ )
|
|
|
+ ),
|
|
|
+ $desc
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Tabel of contents
|
|
|
+ *
|
|
|
+ * Generates a table of contentes out of the whole
|
|
|
+ * project tree.
|
|
|
+ *
|
|
|
+ * @param array $tree The tree array passed from twig
|
|
|
+ * @param int depth Initially this should be 0
|
|
|
+ * @return string
|
|
|
+ **/
|
|
|
+ public static function toc(array $tree, int $depth = 0) {
|
|
|
+
|
|
|
+ // Appending to given string
|
|
|
+ $append = (function(string &$into, int $depth, int $idx, array $elem) {
|
|
|
+
|
|
|
+ // Create a link to this entry
|
|
|
+ $element = self::href($elem[0], $elem[1], is_string($elem[1]), $elem[1]);
|
|
|
+
|
|
|
+ // Get deprecated notice and short description
|
|
|
+ if (self::isReflection($elem[1])) {
|
|
|
+ if (($dep = self::deprecated($elem[1])))
|
|
|
+ $element .= " " . $dep;
|
|
|
+ if (($desc = self::short_description($elem[1])))
|
|
|
+ $element .= " " . $desc;
|
|
|
+ }
|
|
|
+
|
|
|
+ $into .= sprintf("%s%d. %s\n", self::tab($depth), $idx + 1, $element);
|
|
|
+ });
|
|
|
+
|
|
|
+ $str = "";
|
|
|
+
|
|
|
+ foreach ($tree as $key => $elem) {
|
|
|
+ $append($str, $depth, $key, $elem);
|
|
|
+
|
|
|
+ if (isset($elem[2]) && !empty($elem[2])) {
|
|
|
+
|
|
|
+ usort($elem[2], function($a, $b) {
|
|
|
+ return strcmp("" . $a[1], "" . $b[1]);
|
|
|
+ });
|
|
|
+
|
|
|
+ foreach($elem[2] as $key2 => $elem2) {
|
|
|
+ $append($str, ($depth+1), $key2, $elem2);
|
|
|
+ if (isset($elem2[2]) && !empty($elem2[2]))
|
|
|
+ $str .= self::toc($elem2[2], ($depth+2));
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ return $str;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Get hints of a param.
|
|
|
+ *
|
|
|
+ * This could be `string`, `bool` etc or several if an parameter
|
|
|
+ * can be `mixed`. If it's not stated in the functions signature,
|
|
|
+ * the hint will automatically be `mixed`.
|
|
|
+ *
|
|
|
+ * If the hint is a part of this package (root namespace), and
|
|
|
+ * `link` is set to `true` it will return an internal link to the type,
|
|
|
+ * but if link is set to true and the type is
|
|
|
+ *
|
|
|
+ * * [...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list),
|
|
|
+ * * [iterable](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.types) or
|
|
|
+ * * something else
|
|
|
+ *
|
|
|
+ * it will either return a link to this type or add a Google search query-link.
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\ParameterReflection $param The parameter
|
|
|
+ * @param bool $link Set to true to link
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function param_hint(ParameterReflection $param, bool $link = false) {
|
|
|
+ $hints = array();
|
|
|
+
|
|
|
+ // Loop through hints
|
|
|
+ foreach ($param->getHint() as $hint)
|
|
|
+ $hints[] = (function() use ($hint, $link) {
|
|
|
+
|
|
|
+ // If hint is a class (e.g \Sami\Reflection\ClassReflection)
|
|
|
+ if ($hint->isClass()) {
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Sami doesnt know "..." (variable arg list) and "iterable".
|
|
|
+ * It belives it's a class/method or something within the scope
|
|
|
+ * of a namespace.
|
|
|
+ */
|
|
|
+ if ($link && strrpos($hint, "...") == (strlen($hint) - 3))
|
|
|
+ return "[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)";
|
|
|
+ else if (strrpos($hint, "...") == (strlen($hint) - 3))
|
|
|
+ return "...";
|
|
|
+
|
|
|
+ if ($link && strrpos($hint, "iterable") == (strlen($hint) - 8))
|
|
|
+ return "[iterable](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.types)";
|
|
|
+ else if (strrpos($hint, "iterable") == (strlen($hint) - 8))
|
|
|
+ return "iterable";
|
|
|
+
|
|
|
+ // Return name+link (if true) or just name of reference
|
|
|
+ if ($link && ($pos = strrpos($hint, "\\")) !== false && !empty($ns = $hint->getName()->getNamespace()))
|
|
|
+ return self::href(substr($hint, $pos + 1), $hint->getName()->getNamespace());
|
|
|
+ else if (($pos = strrpos($hint, "\\")) !== false)
|
|
|
+ return substr($hint, $pos + 1);
|
|
|
+ }
|
|
|
+
|
|
|
+ return $hint;
|
|
|
+ })();
|
|
|
+
|
|
|
+ return !empty($hints) ? join(" ", $hints) . "" : "mixed";
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Get default for parameter.
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\ParameterReflection $param
|
|
|
+ * @return string|null Null on empty
|
|
|
+ */
|
|
|
+ public static function param_default(ParameterReflection $param) {
|
|
|
+ return !empty($param->getDefault()) ? $param->getDefault() : null;
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Get the methods hints.
|
|
|
+ *
|
|
|
+ * This hints is typically what a method returns, e.g `string`, `bool` etc.
|
|
|
+ *
|
|
|
+ * Method works similar as @see param_hint
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\MethodReflection $method
|
|
|
+ * @param bool $link = false
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function method_hint(MethodReflection $method, bool $link = false) {
|
|
|
+ $hints = array();
|
|
|
+
|
|
|
+ // Loop through hintss
|
|
|
+ foreach ($method->getHint() as $hint)
|
|
|
+ $hints[] = (function() use ($hint, $link) {
|
|
|
+
|
|
|
+ // If class; get name+link if true or just reference name.
|
|
|
+ if ($hint->isClass()) {
|
|
|
+ $name = substr($hint->getName()->getName(), strrpos($hint->getName()->getName(), "\\") + 1);
|
|
|
+
|
|
|
+ return $link ? self::href($name, $hint->getName()->getName()) : $name;
|
|
|
+ }
|
|
|
+ return $hint;
|
|
|
+ })();
|
|
|
+
|
|
|
+ // Join with v (mathically OR) to not break tables.
|
|
|
+ return join(" ***v*** ", $hints);
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Get access to method.
|
|
|
+ *
|
|
|
+ * Returns if a method is abstract, final, protected etc. Access
|
|
|
+ * to a method can be a mix and this method will include every.
|
|
|
+ *
|
|
|
+ * @param MethodReflection $method
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function method_access(MethodReflection $method) {
|
|
|
+ $sign = array();
|
|
|
+
|
|
|
+ if ($method->isAbstract())
|
|
|
+ $sign[] = "abstract";
|
|
|
+
|
|
|
+ if ($method->isFinal())
|
|
|
+ $sign[] = "final";
|
|
|
+
|
|
|
+ if ($method->isProtected())
|
|
|
+ $sign[] = "protected";
|
|
|
+
|
|
|
+ if ($method->isPrivate())
|
|
|
+ $sign[] = "private";
|
|
|
+
|
|
|
+ if ($method->isPublic())
|
|
|
+ $sign[] = "public";
|
|
|
+
|
|
|
+ if ($method->isStatic())
|
|
|
+ $sign[] = "static";
|
|
|
+
|
|
|
+ return join(" ", $sign);
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Get signature of a method.
|
|
|
+ *
|
|
|
+ * Returns the function name, parameters and access. It
|
|
|
+ * also includes default parameter values if `$incname` is
|
|
|
+ * set to true.
|
|
|
+ *
|
|
|
+ * The format will be
|
|
|
+ * ```php
|
|
|
+ * access function name(paramterers [= "value"]);
|
|
|
+ * ```
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\MethodReflection $method Method reflection
|
|
|
+ * @param bool $incname Adds default parameter values on true
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function method_signature(MethodReflection $method, bool $incname = true) {
|
|
|
+
|
|
|
+ $sign = array();
|
|
|
+
|
|
|
+ // Loop through params
|
|
|
+ foreach ($method->getParameters() as $param)
|
|
|
+ $sign [] = sprintf("%s%s",
|
|
|
+ self::param_hint($param),
|
|
|
+ (function() use ($param, $incname) {
|
|
|
+ if (!$incname)
|
|
|
+ return null;
|
|
|
+
|
|
|
+ $var = sprintf(" $%s", $param->getName());
|
|
|
+
|
|
|
+ if (!empty($param->getDefault()))
|
|
|
+ $var = sprintf("%s = %s", $var, $param->getDefault());
|
|
|
+
|
|
|
+ return $var;
|
|
|
+ })($param)
|
|
|
+ );
|
|
|
+
|
|
|
+ return sprintf("%s(%s);", $method->getName(), join(", ", $sign));
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Return a link to method in source code.
|
|
|
+ *
|
|
|
+ * @todo Investigate! Doesnt work as expected. sourcePath is always `null`.
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection MethodReflection $method Method reflection
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function method_source_url(MethodReflection $method) {
|
|
|
+ if (empty($method->getClass()->getSourcePath()))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ return "\n> [File: ok.php#L](" . $method->getClass()->getSourcePath() . ")";
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Pretty print table.
|
|
|
+ *
|
|
|
+ * Makes a better readable format of a table when
|
|
|
+ * reading the source-code of the markdown directly.
|
|
|
+ *
|
|
|
+ * Note that each array-entry can contain several rows, but
|
|
|
+ * rows must the be separated with `\n`.
|
|
|
+ *
|
|
|
+ * @param array &$arr Array containg each row in a table
|
|
|
+ */
|
|
|
+ private static function pp_tbl(array &$arr) {
|
|
|
+
|
|
|
+ if (empty($arr) || !self::$pretty_print)
|
|
|
+ return;
|
|
|
+
|
|
|
+ // Count rows
|
|
|
+ $cols = substr_count(explode("\n", $arr[0])[0], "|");
|
|
|
+ // And fill an array
|
|
|
+ $cmax = array_fill(0, $cols, 0);
|
|
|
+
|
|
|
+ // Loop through each entry in array
|
|
|
+ foreach($arr as $key => $line) {
|
|
|
+ $h = 0; // Last column separator position
|
|
|
+ $col = 0;
|
|
|
+
|
|
|
+ // And each character in entry
|
|
|
+ for($i = 0; $i < strlen($line); $i++) {
|
|
|
+
|
|
|
+ // To work with entries with several rows in an entry
|
|
|
+ if ($line[$i] == "\n") {
|
|
|
+ $h = $i;
|
|
|
+ continue;
|
|
|
+ }
|
|
|
+
|
|
|
+ // Hit column separator
|
|
|
+ if ($line[$i] == "|") {
|
|
|
+
|
|
|
+ // Find longes column
|
|
|
+ if (($i-$h) > $cmax[$col % $cols])
|
|
|
+ $cmax[$col % $cols] = ($i - $h - 1);
|
|
|
+
|
|
|
+ $h = $i;
|
|
|
+ $col++;
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ // Do the same as above
|
|
|
+ foreach($arr as $key => $line) {
|
|
|
+ $h = 0; // Last column separator position
|
|
|
+ $col = 0;
|
|
|
+
|
|
|
+ // Clear array entry
|
|
|
+ $arr[$key] = "";
|
|
|
+
|
|
|
+ for($i = 0; $i < strlen($line); $i++) {
|
|
|
+
|
|
|
+ if ($line[$i] == "\n") {
|
|
|
+ $arr[$key] .= "|";
|
|
|
+ $h = $i;
|
|
|
+ continue;
|
|
|
+ }
|
|
|
+
|
|
|
+ if ($line[$i] == "|") {
|
|
|
+ // Get the conten from $h to $i (content of column)
|
|
|
+ $lead = substr($line, $h, $i - $h);
|
|
|
+
|
|
|
+ // Check if it must be padded with spaces
|
|
|
+ if (($i - $h) < $cmax[$col % $cols])
|
|
|
+ $lead .= str_repeat(" ", $cmax[$col % $cols] - ($i - $h) + 1);
|
|
|
+
|
|
|
+ // Restore array entry
|
|
|
+ $arr[$key] .= $lead . (($i + 1) == strlen($line) ? "|" : "");
|
|
|
+
|
|
|
+ $h = $i;
|
|
|
+ $col++;
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Render methods.
|
|
|
+ *
|
|
|
+ * Returns a summary and detailed description of every
|
|
|
+ * method in the method array.
|
|
|
+ *
|
|
|
+ * @param array $methods
|
|
|
+ * @return string|null Null on empty
|
|
|
+ */
|
|
|
+ public static function render_methods(array $methods) {
|
|
|
+
|
|
|
+ // No methods here... return
|
|
|
+ if (empty($methods))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ // Table layout | left padding | left p | left p | left p |
|
|
|
+ $tbl = array("|Name|Return|Access|Description|\n|:---|:---|:---|:---|");
|
|
|
+
|
|
|
+ // Create the summary
|
|
|
+ foreach ($methods as $method)
|
|
|
+ $tbl[] = sprintf("|%s|%s|%s| %s|",
|
|
|
+ self::href($method->getName(), $method->getClass()->getName() . "\\" . $method->getName()),
|
|
|
+ self::method_hint($method, true),
|
|
|
+ self::method_access($method),
|
|
|
+ self::short_description($method)
|
|
|
+ );
|
|
|
+
|
|
|
+ // Fix layout of table
|
|
|
+ self::pp_tbl($tbl);
|
|
|
+
|
|
|
+ $details = array();
|
|
|
+
|
|
|
+ // 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",
|
|
|
+ $method->getName(), $method->getClass()->getName(),
|
|
|
+ self::method_access($method),
|
|
|
+ self::method_signature($method),
|
|
|
+
|
|
|
+ // Method description, padded left with > (block/indent)
|
|
|
+ (function() use ($method) {
|
|
|
+ if (empty(self::long_description($method)))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ return "\n " . self::long_description($method) . "\n";
|
|
|
+ })(),
|
|
|
+
|
|
|
+ // TODO: Debug this. No output?
|
|
|
+ self::method_source_url($method),
|
|
|
+
|
|
|
+ // Method parameters in table with description
|
|
|
+ (function() use ($method) {
|
|
|
+
|
|
|
+ // No parameters, skip
|
|
|
+ if (empty($method->getParameters()))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ // Layout table
|
|
|
+ $params = array("| Type | Variable | Description |", "|---|---|---|");
|
|
|
+
|
|
|
+ foreach ($method->getParameters() as $param)
|
|
|
+ $params[] = sprintf("|%s|$%s|%s|",
|
|
|
+ self::param_hint($param, true),
|
|
|
+ $param->getName(),
|
|
|
+ !empty(self::long_description($param)) ? self::long_description($param) : '*None*'
|
|
|
+ );
|
|
|
+
|
|
|
+ self::pp_tbl($params);
|
|
|
+
|
|
|
+ array_unshift($params, "Parameters\n");
|
|
|
+ // Return padded..
|
|
|
+ return "\n" . self::join($params);
|
|
|
+ })(),
|
|
|
+
|
|
|
+ // Method returns
|
|
|
+ (!empty($method->getHint()) ? "\n\nReturns: " . self::method_hint($method, true) . "\n" : null),
|
|
|
+
|
|
|
+ // Method throws
|
|
|
+ (function () use ($method) {
|
|
|
+
|
|
|
+ // Nothing... skip
|
|
|
+ if (empty($method->getExceptions()))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ // Return exceptions padded whith > and linked to...
|
|
|
+ return "\n> Throws: " . (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";
|
|
|
+ })();
|
|
|
+ })(),
|
|
|
+
|
|
|
+ (function() use ($method) {
|
|
|
+
|
|
|
+ if (empty(self::todo($method)))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ return "\n> Todo: " . self::join(self::todo($method), "> * ") . "\n";
|
|
|
+ })()
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ if (!empty($details))
|
|
|
+ array_unshift($details, "\n#### Method details");
|
|
|
+
|
|
|
+ return sprintf(
|
|
|
+ "\n#### Methods\n%s%s",
|
|
|
+ self::join($tbl),
|
|
|
+ self::join($details)
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Render class
|
|
|
+ *
|
|
|
+ * Returns information about a class including it's methods.
|
|
|
+ *
|
|
|
+ * @param \Sami\Reflection\ClassReflection $class Class reflection
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function render_class(ClassReflection $class) {
|
|
|
+
|
|
|
+ return sprintf(
|
|
|
+ "\n### %s `%s`\n%s%s%s",
|
|
|
+ $class->getShortName(),
|
|
|
+ $class->getNamespace(),
|
|
|
+
|
|
|
+ // Get class info
|
|
|
+ (function() use ($class) {
|
|
|
+ $notes = array();
|
|
|
+
|
|
|
+ if (!empty($depr = self::deprecated($class, false)))
|
|
|
+ $notes[] = $depr;
|
|
|
+
|
|
|
+ if ($class->isAbstract())
|
|
|
+ $notes[] = "Class is abstact";
|
|
|
+
|
|
|
+ if ($class->isFinal())
|
|
|
+ $notes[] = "Class is final";
|
|
|
+
|
|
|
+ if (!empty($class->getParent()))
|
|
|
+ $notes[] = sprintf("Class extends %s", self::href($class->getParent()->getName(), $class->getParent()->getName()));
|
|
|
+
|
|
|
+ if (!empty($ifaces = $class->getInterfaces(true))) {
|
|
|
+ $interfaces = array();
|
|
|
+ foreach($ifaces as $interface)
|
|
|
+ $interfaces[] = self::href($interface->getName(), $interface->getName());
|
|
|
+ if (count($interfaces) == 1)
|
|
|
+ $notes[] = "Class implements" . $interfaces[0];
|
|
|
+ else
|
|
|
+ $notes[] = "Class implements" . self::join($interfaces, "* ", "\n\t");
|
|
|
+ }
|
|
|
+
|
|
|
+ if (!empty($tr = $class->getTraits())) {
|
|
|
+ $traits = array();
|
|
|
+ foreach($tr as $trait)
|
|
|
+ $traits[] = self::href($trait->getName(), $trait->getName());
|
|
|
+ if (count($traits) == 1)
|
|
|
+ $notes[] = "Class uses " . $traits[0];
|
|
|
+ else
|
|
|
+ $notes[] = "Class uses" . self::join($traits, "* ", "\n\t");
|
|
|
+ }
|
|
|
+
|
|
|
+ if (empty($notes))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ return "\n" . self::join($notes, "* ", "\n") . "\n";
|
|
|
+ })(),
|
|
|
+
|
|
|
+ // Get full description
|
|
|
+ (function() use ($class) {
|
|
|
+ if (empty(self::long_description($class)))
|
|
|
+ return null;
|
|
|
+ return "\n" . self::long_description($class) . "\n";
|
|
|
+ })(),
|
|
|
+
|
|
|
+ self::render_methods($class->getMethods())
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Render one or more classes.
|
|
|
+ *
|
|
|
+ * Should typically be used for a single namespace at the time.
|
|
|
+ *
|
|
|
+ * Determines which kind of class (e.g trait, interface etc)
|
|
|
+ * and returns them in the structure/order
|
|
|
+ *
|
|
|
+ * Namespace
|
|
|
+ * * Normal classes,
|
|
|
+ * * Traits,
|
|
|
+ * * Interfaces,
|
|
|
+ * * Exceptions.
|
|
|
+ *
|
|
|
+ * @param array $classes Array with ClassReflection
|
|
|
+ * @return string|null Null on empty
|
|
|
+ */
|
|
|
+ public static function render_classes(array $classes) {
|
|
|
+
|
|
|
+ if (empty($classes))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ $traits = array();
|
|
|
+ $exceptions = array();
|
|
|
+ $interfaces = array();
|
|
|
+
|
|
|
+ // Separate classes
|
|
|
+ foreach($classes as $name => $class) {
|
|
|
+ if ($class->isTrait()) {
|
|
|
+ $traits[] = $class;
|
|
|
+ unset($classes[$name]);
|
|
|
+ } else if ($class->isException() || strpos($class->getNamespace(), "Exception") !== false) {
|
|
|
+ $exceptions[] = $class;
|
|
|
+ unset($classes[$name]);
|
|
|
+ } else if ($class->isInterface()) {
|
|
|
+ $interfaces[] = $class;
|
|
|
+ unset($classes[$name]);
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ if (!empty($classes)) {
|
|
|
+ foreach($classes as $name => $class)
|
|
|
+ $classes[$name] = self::render_class($class);
|
|
|
+ array_unshift($classes, "## Classes");
|
|
|
+ }
|
|
|
+
|
|
|
+ if (empty($traits) && empty($exceptions) && empty($interfaces) && empty($classes))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ if (!empty($traits)) {
|
|
|
+ foreach($traits as $key => $trait)
|
|
|
+ $traits[$key] = self::render_class($trait);
|
|
|
+ array_unshift($t, "## Traits");
|
|
|
+ }
|
|
|
+
|
|
|
+ if (!empty($interfaces)) {
|
|
|
+ foreach($interfaces as $key => $interface)
|
|
|
+ $interface[$key] = self::render_class($interface);
|
|
|
+ array_unshift($i, "## Interfaces");
|
|
|
+ }
|
|
|
+
|
|
|
+ if (!empty($exceptions)) {
|
|
|
+ foreach($exceptions as $key => $exception)
|
|
|
+ $exceptions[$key] = self::render_class($exception);
|
|
|
+ array_unshift($e, "## Exceptions");
|
|
|
+ }
|
|
|
+ return sprintf("%s%s%s%s",
|
|
|
+ self::join($classes),
|
|
|
+ self::join($traits),
|
|
|
+ self::join($interfaces),
|
|
|
+ self::join($exceptions));
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Render namespace.
|
|
|
+ *
|
|
|
+ * Returns information about the whole namespace, as long as
|
|
|
+ * it's sub-namespaces and classes is passed along to the method.
|
|
|
+ *
|
|
|
+ * @param string $namespace The name of the namespace
|
|
|
+ * @param array $namespaces Array with names of sub-namespaces
|
|
|
+ * @param array $classes Array with ClassReflections
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function render_namespace(string $namespace, array $namespaces, array $classes) {
|
|
|
+
|
|
|
+ return sprintf(
|
|
|
+ "\n# %s\n%s",
|
|
|
+ $namespace,
|
|
|
+ empty($classes) ? (
|
|
|
+ function () use ($namespaces) {
|
|
|
+ if (empty($namespaces))
|
|
|
+ return null;
|
|
|
+
|
|
|
+ $links = array();
|
|
|
+
|
|
|
+ foreach ($namespaces as $namespace)
|
|
|
+ array_push($links, self::href($namespace, $namespace, true, "Namespace: " . $namespace));
|
|
|
+
|
|
|
+ return "\n * " . join("\n * ", $links) . "\n";
|
|
|
+ }
|
|
|
+ )(): self::render_classes($classes)
|
|
|
+ );
|
|
|
+ }
|
|
|
+
|
|
|
+ /**
|
|
|
+ * Render the whole ReadMe.
|
|
|
+ *
|
|
|
+ * Will bind classes and it's sub-namespaces and render namespace
|
|
|
+ * for namespace.
|
|
|
+ *
|
|
|
+ * @param array $namespaces Array with names of namespaces
|
|
|
+ * @param array $classes Array with ClassReflections
|
|
|
+ * @return string
|
|
|
+ */
|
|
|
+ public static function render(array $namespaces, array $classes) {
|
|
|
+
|
|
|
+ $str = "";
|
|
|
+
|
|
|
+ foreach($namespaces as $namespace) {
|
|
|
+ $nsclasses = array();
|
|
|
+ $nss = array();
|
|
|
+
|
|
|
+ foreach($classes as $name => $class) {
|
|
|
+ if ($class->getNamespace() == $namespace) {
|
|
|
+ $nsclasses[$name] = $class;
|
|
|
+ unset($classes[$name]);
|
|
|
+ }
|
|
|
+
|
|
|
+ if (!empty($class->getNamespace()) && !empty($namespace)) {
|
|
|
+ if (!in_array($class->getNamespace(), $nss) && strpos($class->getNamespace(), $namespace) !== false)
|
|
|
+ $nss[$name] = $class->getNamespace();
|
|
|
+ }
|
|
|
+ }
|
|
|
+
|
|
|
+ $str .= self::render_namespace($namespace, $nss, $nsclasses);
|
|
|
+ }
|
|
|
+
|
|
|
+ return $str . "\n\n - Genetated using Sami and the [Sami/Twig Markdown Extension](https://git.giaever.org/joachimmg/sami-markdown)";
|
|
|
+ }
|
|
|
+}
|
|
|
+
|
|
|
+?>
|
