:note: PhpDoc generation for the public API (#63)

- generate phpdoc to a dokuwiki compatible format
- add/update the phpdoc of a selection of class methods

.doc/phpdoc-templates/combodo-wiki/includes/code-examples.txt.twig

@@ -0,0 +1,34 @@
+{% if title_level is not defined %}
+    {%- set title_level = '==' -%}
+{% endif %}
+
+{% if sub_title_level is not defined %}
+    {%- set sub_title_level = title_level|slice(1) -%}
+{% endif %}
+{% if sub_title_level == '=' %}
+    {%- set sub_title_level = '' -%}
+{% endif %}
+
+{#{% for tagName,tags in structure.tags if tagName in ['code-example'] %}#}
+{#{% if loop.first %}#}
+{#{{title_level}} Examples {{title_level}}#}
+{#{% endif %}#}
+{#{% for tag in tags %}#}
+{#{%- set descToken = tag.description|split("\n", 2) -%}#}
+{#{%- set title = descToken[0] -%}#}
+{#{%- set code = descToken[1] -%}#}
+{#{{sub_title_level}} {{ title }} {{sub_title_level}}#}
+{#<code php>{{ code|raw }}</code>#}
+{#{% endfor %}#}
+{#{% endfor %}#}
+
+
+{% for tagName,tags in structure.tags if tagName in ['example'] %}
+{% if loop.first %}
+{{title_level}} Examples {{title_level}}
+{% endif %}
+{% for tag in tags %}
+{{ sub_title_level }} {{ tag.filePath|escape }}{{ sub_title_level }}
+<code php>{{ tag.description|raw }}</code>
+{% endfor %}
+{% endfor %}

.doc/phpdoc-templates/combodo-wiki/includes/inherited-from.txt.twig

@@ -0,0 +1,12 @@
+{% if title_level is not defined %}
+    {% set title_level='' %}
+{% endif %}
+
+{% if (node.parent is null) %}
+{{title_level}} File {{ structure.path }} {{title_level}}
+{% endif %}
+
+{% if (node.parent is not null and structure.parent.fullyQualifiedStructuralElementName != node.fullyQualifiedStructuralElementName) %}
+{{title_level}} Inherited from {{title_level}}
+[[{{structure.parent}}|{{structure.parent}}]]
+{% endif %}

.doc/phpdoc-templates/combodo-wiki/includes/namespace-structure-toc.html.twig

@@ -0,0 +1,26 @@
+{% for structure in structures|sort_asc if structure.tags['internal'] is not defined and (structure.tags['api'] is defined or structure.tags['api-advanced'] is  defined or structure.tags['overwritable-hook'] is  defined or structure.tags['extension-hook'] is  defined ) %}
+{#{{ structure|raw }}#}
+
+{% set structureName = structure|trim('\\', 'left') %}
+
+<WRAP group box>
+<WRAP twothirds column >
+==== {{ structureName }} ====
+</WRAP>{# twothirds column#}
+
+<WRAP third column>
+{% if structure.deprecated %}<wrap danger>deprecated</wrap>{% endif %}
+{% if structure.abstract %}<wrap warning>abstract</wrap>{% endif %}
+{% if structure.final %}<wrap notice>final</wrap>{% endif %}
+{% if (node.parent is not null and structure.parent.fullyQualifiedStructuralElementName != node.fullyQualifiedStructuralElementName) %}<wrap notice>inherited</wrap> {% endif %}
+{% include 'includes/wrap-tags.txt.twig' with {structure:structure, wrap: 'safety', wrapTags: ['api', 'api-advanced', 'overwritable-hook', 'extension-hook']} %}
+</WRAP>{# third column#}
+
+
+{{ structure.summary|raw }}
+[[{{structureName}}|More informations]]
+
+</WRAP>{# group #}
+
+{% endfor %}
+

.doc/phpdoc-templates/combodo-wiki/includes/see-also.txt.twig

@@ -0,0 +1,26 @@
+{% if title_level is not defined %}
+    {%- set title_level='==' -%}
+{% endif %}
+{% for tagName,tags in structure.tags if tagName in ['link', 'see'] %}
+{% if loop.first %}
+{{title_level}} See also {{title_level}}
+{% endif %}
+{% for tag in tags %}
+{%- set linkTag = tag.reference|trim('\\', 'left') -%}
+{% if not('()' in linkTag or '$' in linkTag or node.name in linkTag or  '::' in linkTag ) %}
+    {%- set linkTag = linkTag|lower -%}
+{% elseif node.name~'::' in linkTag %}
+    {%- set linkTag = linkTag|replace({(node.name~'::'): '#'})|lower -%}
+{% elseif '::' in linkTag -%}
+    {%- set linkTag = linkTag|replace({'::': '#'})|lower -%}
+{% else %}
+    {%- set linkTag = '#' ~ linkTag|lower -%}
+{%- endif %}
+
+{% if loop.length > 1 %}  * {% endif %}{% if tag.reference is not empty -%}
+    [[{{linkTag}}|{{ (tag.reference)|trim('\\', 'left') }}]] {% if tag.description|trim is not empty %}: {{ tag.description|trim('\\', 'left') }} {% endif %}
+{%- else -%}
+    {#{{ tag.description|trim('\\', 'left') }}#}
+{% endif %}
+{% endfor %}
+{% endfor %}

.doc/phpdoc-templates/combodo-wiki/includes/tag-synthesys.txt.twig

@@ -0,0 +1,56 @@
+{% if tag is not defined -%}
+    {# Do not display @api if @api-advanced is also present #}
+    {%- set tag = "api" -%}
+{%- endif %}
+
+{% if hidden_by is not defined -%}
+    {# Do not display @api if @api-advanced is also present #}
+    {%- set hidden_by = {"api" : "api-advanced"} -%}
+{%- endif %}
+
+
+
+{% for method in methods|sort_asc
+    if (method.visibility == 'public')
+    and (
+        method.tags[tag] is defined
+        and (
+            hidden_by[tag] is not defined or method.tags[hidden_by[tag]] is not defined
+        )
+    )
+%}
+{%- if loop.first %}
+{% if tag == 'api' %}
+===== API synthesis =====
+<WRAP>
+List of the public API methods.
+When manipulating {{ node.name }}, You can call those methods:
+</WRAP>
+{% elseif tag == 'api-advanced' %}
+===== Advanced API synthesis =====
+<WRAP>
+List of advanced API methods
+Beware they usage is recommended to advanced users only.
+</WRAP>
+{% elseif tag == 'overwritable-hook' %}
+===== overwritable-hook synthesis =====
+<WRAP >When inheriting from {{ node.name }},
+you can overwrite those methods in order to add custom logic:
+</WRAP>
+{% elseif tag == 'extension-hook' %}
+===== extension-hook synthesis =====
+<WRAP >
+When inheriting from {{ node.name }},
+you can extend the behaviour of iTop by implementing:
+</WRAP>
+{% endif %}
+{% endif %}
+{% set sanitizedMethod = method|trim('\\', 'left')|replace({(node.name~'::'): ''}) %}
+{% if '::' in sanitizedMethod -%}
+{%- if node.tags['phpdoc-tunning-exclude-inherited'] is not defined %}
+  * [[{{sanitizedMethod|replace({'::': '#'})|lower}}|↪{{sanitizedMethod}}]] — {{  method.summary|replace({"\n":""})|raw }}
+{% endif %}
+{%- else %}
+  * [[#{{sanitizedMethod}}|{{sanitizedMethod}}]] — {{  method.summary|replace({"\n":""})|raw }}
+{% endif %}
+{% endfor %}

.doc/phpdoc-templates/combodo-wiki/includes/tags-with-description.txt.twig

@@ -0,0 +1,20 @@
+{% if title_level is not defined %}
+    {% set title_level = '==' %}
+{% endif %}
+
+
+{%- for tagName,tags in structure.tags if tagName in tagsWithDescription -%}
+    {%- for tag in tags -%}
+        {%- if tag.description is not empty -%}
+{%- if WRAP is defined -%}
+    <WRAP {{WRAP}}>
+{%- endif -%}
+{{title_level}} {{ tagName }} {{title_level}}
+{{ tag.description|escape }}
+{%- if WRAP is defined -%}
+    </WRAP>
+{%- endif -%}
+        {%- endif -%}
+    {%- endfor -%}
+{%- endfor -%}
+

.doc/phpdoc-templates/combodo-wiki/includes/tags.txt.twig

@@ -0,0 +1,22 @@
+{% if title_level is not defined %}
+    {% set title_level='=====' %}
+{% endif %}
+
+{% if blacklist is not defined %}
+    {% set blacklist =['link', 'see', 'abstract', 'example', 'method', 'property', 'property-read', 'property-write', 'package', 'subpackage', 'api', 'api-advanced', 'todo', 'code-example'] %}
+{% endif %}
+{% if hidden_by is not defined -%}
+    {# Do not display @api if @api-advanced is also present #}
+    {%- set hidden_by = {"api" : "api-advanced"} -%}
+{%- endif %}
+
+{#^ {% for tagName,tags in structure.tags if tagName not in blacklist -%}#}
+{#{{ tagName }} ^#}
+{#{%- endfor %}#}
+
+{% for tagName,tags in structure.tags if tagName not in blacklist and (hidden_by[tagName] is not defined or structure.tags[hidden_by[tagName]] is not defined) %}
+{%- if loop.first %}
+{{title_level}} Tags {{title_level}}
+{% endif %}
+^ {{ tagName }} | {% for tag in tags %}{{ tag.version ? tag.version ~ ' '  : '' }}{{ tag.description}}{% endfor %}   |
+{% endfor %}

.doc/phpdoc-templates/combodo-wiki/includes/used-by.txt.twig

@@ -0,0 +1,24 @@
+{% if title_level is not defined %}
+    {% set title_level='' %}
+{% endif %}
+{% for tagName,tags in structure.tags if tagName in ['used-by'] %}
+{% if loop.first %}
+{{title_level}} Used by {{title_level}}
+{% endif %}
+{% for tag in tags %}
+{% if loop.length > 1 %}  * {% endif %}{{ tag.reference ?: tag.link }} : {{ tag.description ?: tag.reference }}
+{% endfor %}
+{% endfor %}
+
+
+
+
+
+{#{% for tagName,tags in method.tags if tagName in ['uses'] %}#}
+    {#{% if loop.first %}#}
+        {#<dt>Uses</dt>#}
+    {#{% endif %}#}
+    {#{% for tag in tags %}#}
+        {#<dd>{{ tag.reference|raw }}</dd>#}
+    {#{% endfor %}#}
+{#{% endfor %}#}

.doc/phpdoc-templates/combodo-wiki/includes/uses.txt.twig

@@ -0,0 +1,24 @@
+{% if title_level is not defined %}
+    {% set title_level='' %}
+{% endif %}
+{% for tagName,tags in structure.tags if tagName in ['uses'] %}
+{% if loop.first %}
+{{title_level}} Uses {{title_level}}
+{% endif %}
+{% for tag in tags %}
+{% if loop.length > 1 %}  * {% endif %}{{ tag.reference ?: tag.link }} : {{ tag.description ?: tag.reference }}
+{% endfor %}
+{% endfor %}
+
+
+
+
+
+{#{% for tagName,tags in method.tags if tagName in ['uses'] %}#}
+    {#{% if loop.first %}#}
+        {#<dt>Uses</dt>#}
+    {#{% endif %}#}
+    {#{% for tag in tags %}#}
+        {#<dd>{{ tag.reference|raw }}</dd>#}
+    {#{% endfor %}#}
+{#{% endfor %}#}

.doc/phpdoc-templates/combodo-wiki/includes/wrap-tags.txt.twig

@@ -0,0 +1,11 @@
+{% if wrap is not defined -%}
+    {% set wrap = 'notice' %}
+{%- endif -%}
+{% if hidden_by is not defined -%}
+    {# Do not display @api if @api-advanced is also present #}
+    {%- set hidden_by = {"api" : "api-advanced"} -%}
+{%- endif %}
+
+{%- for tagName,tags in structure.tags if tagName in wrapTags and (hidden_by[tagName] is not defined or structure.tags[hidden_by[tagName]] is not defined) %}
+ <wrap {{wrap}}>{{tagName}}</wrap>
+{% endfor %}