sami-markdown/README.md

Sami Markdown Extension

Table of content

1. Markdown
   1. SamiTwigExtension An extension than builds a single ReadMe markdownfile out of your code.

---

Documentation

Markdown

Classes

SamiTwigExtension Markdown

• Class extends Twig_Extension

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 and fork this repo

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:

$sami["twig"]->addExtension(new Markdown\SamiTwigExtension());

Methods

Name	Return	Access	Description
__construct		public
getFunctions		public	Set the functions available for the template engine.
short_description	string v null	public static	Returns the short description of a reflection.
long_description	string v null	public static	Returns a long description (both short and long) of a reflection.
deprecated	string v null	public static	Returnes a deprecated label if class, method etc is.
todo	array v null	public static	Returns todo-tag for Reflection.
see	array v null	public static	Returns see-tag for Reflection.
href	string	public static	Returnes a markdown link.
toc	string	public static	Tabel of contents
param_hint	string	public static	Get hints of a param.
param_default	string v null	public static	Get default for parameter.
method_hint	string	public static	Get the methods hints.
method_access	string	public static	Get access to method.
method_signature	string	public static	Get signature of a method.
method_source_url	string	public static	Return a link to method in source code.
render_methods	string v null	public static	Render methods.
render_class	string	public static	Render class
render_classes	string v null	public static	Render one or more classes.
render_namespace	string	public static	Render namespace.
render	string	public static	Render the whole ReadMe.

Method details

__construct Markdown\SamiTwigExtension

public function __construct(bool $pretty_print = false);

Parameters

Type	Variable	Description
bool	$pretty_print	None

---

getFunctions Markdown\SamiTwigExtension

public function getFunctions();

Set the functions available for the template engine.

---

short_description Markdown\SamiTwigExtension

public static function short_description(Reflection $refl, bool $oneliner = true, int $max = -1);

Returns the short description of a reflection.

Parameters

Type	Variable	Description
Reflection	$refl	Reflection to return description of
bool	$oneliner	Removes every newline and tabulation.
int	$max	Maximum of letters

Returns: string v null

---

long_description Markdown\SamiTwigExtension

public static function long_description(Reflection $refl, bool $oneliner = false);

Returns a long description (both short and long) of a reflection.

Parameters

Type	Variable	Description
Reflection	$refl	Reflection to return description of
bool	$oneliner	Removes every newline and tabulation

Returns: string v null

---

deprecated Markdown\SamiTwigExtension

public static function deprecated(Reflection $refl, bool $notice = true);

Returnes a deprecated label if class, method etc is.

If $notice is false, it will include the deprecated note - if given in the documentation.

Parameters

Type	Variable	Description
Reflection	$refl	Reflection
bool	$notice	Just as notice

Returns: string v null

---

todo Markdown\SamiTwigExtension

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

public static function see(Reflection $refl);

Returns see-tag for Reflection.

Parameters

Type	Variable	Description
Reflection	$refl	Reflection to get see-tag from.

Returns: array v null

---

href Markdown\SamiTwigExtension

public static function href(string $ltxt, string $lurl, bool $namespace = false, string $desc = 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.

Parameters

Type	Variable	Description
string	$ltxt	The link text
string	$lurl	The link destination
bool	$namespace	True when linking to a namespace
string	$desc	Link title (like the html title/hover-tag)

Returns: string

---

toc Markdown\SamiTwigExtension

public static function toc(array $tree, int $depth);

Tabel of contents

Generates a table of contentes out of the whole project tree.

Parameters

Type	Variable	Description
array	$tree	The tree array passed from twig
int	$depth	depth Initially this should be 0

Returns: string

---

param_hint Markdown\SamiTwigExtension

public static function param_hint(ParameterReflection $param, bool $link = false);

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

• ...,
• iterable or
• something else

it will either return a link to this type or add a Google search query-link.

Parameters

Type	Variable	Description
ParameterReflection	$param	The parameter
bool	$link	Set to true to link

Returns: string

---

param_default Markdown\SamiTwigExtension

public static function param_default(ParameterReflection $param);

Get default for parameter.

Parameters

Type	Variable	Description
ParameterReflection	$param	None

Returns: string v null

---

method_hint Markdown\SamiTwigExtension

public static function method_hint(MethodReflection $method, bool $link = false);

Get the methods hints.

This hints is typically what a method returns, e.g string, bool etc.

Method works similar as param_hint.

Parameters

Type	Variable	Description
MethodReflection	$method	None
bool	$link	= false

Returns: string

---

method_access Markdown\SamiTwigExtension

public static function method_access(MethodReflection $method);

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.

Parameters

Type	Variable	Description
MethodReflection	$method	None

Returns: string

---

method_signature Markdown\SamiTwigExtension

public static function method_signature(MethodReflection $method, bool $incname = true);

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

access function name(paramterers [= "value"]);

Parameters

Type	Variable	Description
MethodReflection	$method	Method reflection
bool	$incname	Adds default parameter values on true

Returns: string

---

method_source_url Markdown\SamiTwigExtension

public static function method_source_url(MethodReflection $method);

Return a link to method in source code.

Parameters

Type	Variable	Description
MethodReflection	$method	MethodReflection $method Method reflection

Returns: string

---

render_methods Markdown\SamiTwigExtension

public static function render_methods(array $methods);

Render methods.

Returns a summary and detailed description of every method in the method array.

Parameters

Type	Variable	Description
array	$methods	None

Returns: string v null

---

render_class Markdown\SamiTwigExtension

public static function render_class(ClassReflection $class);

Render class

Returns information about a class including it's methods.

Parameters

Type	Variable	Description
ClassReflection	$class	Class reflection

Returns: string

---

render_classes Markdown\SamiTwigExtension

public static function render_classes(array $classes);

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.

Parameters

Type	Variable	Description
array	$classes	Array with ClassReflection

Returns: string v null

---

render_namespace Markdown\SamiTwigExtension

public static function render_namespace(string $namespace, array $namespaces, array $classes);

Render namespace.

Returns information about the whole namespace, as long as it's sub-namespaces and classes is passed along to the method.

Parameters

Type	Variable	Description
string	$namespace	The name of the namespace
array	$namespaces	Array with names of sub-namespaces
array	$classes	Array with ClassReflections

Returns: string

---

render Markdown\SamiTwigExtension

public static function render(array $namespaces, array $classes);

Render the whole ReadMe.

Will bind classes and it's sub-namespaces and render namespace for namespace.

Parameters

Type	Variable	Description
array	$namespaces	Array with names of namespaces
array	$classes	Array with ClassReflections

Returns: string

---

• Genetated using Sami and the Sami/Twig Markdown Extension