:note: PhpDoc generation for the public API

- typo (tunning => tuning)
 - rework of the README.md

.doc/README.md

@@ -1,52 +1,103 @@
-# phpdoc dokuwiki template
+# Phpdoc dokuwiki template
 This directory contains a template rendering iTop phpdoc as wiki pages.
 
 
+conventional tag that you should use:
+ * `@internal` : exclude from the documentation.
+ * `@api` : it means that a method is an api, thus it may be interacted with.
+ * `@see` : it points to another documented method
+ * `@link` : external url 
+   * if you point to another page of the wiki, please use relative links.
+ * `@example` : let you provide example of code
+ * `@param`, `@return`, `@throws`, ... 
 
-## special instructions
+
+## Special instructions
 
 some tags where added : 
  * `@api-advanced`: it means that a method is an `@api` but mark it also as "complex" to use
  * `@overwritable-hook`: used to mark a method as "designed to be extended"
  * `@extension-hook`: not used for now 
- * `@phpdoc-tunning-exclude-inherited`: tunning tag that inform this template to ignere inherited methods in the rendrering.
+ * `@phpdoc-tuning-exclude-inherited`: once this tag is present on a class, it's inherited methods won't be showed.
 
-some behaviours where added :
- * only public `@api` and `@api-advanced` are shown
- * class properties are hidden (subject to change, but will require to white list them using `@api` tag)
  
-known limitations:
- * inline tags do not work properly
- * links are hardcoded instead of using phpdoc routes (adding our own routes was too complex)
- * `@see` tags must be very specific: 
-   * always prefix class members with `Class::` (ie: `DBObject::Get()`) 
+### known limitations:
+#### `@see` tags must be very specific: 
+   * always prefix class members with `ClassName::` 
    * for methods always suffix them with `()`, 
-   * for variables, always prefix them with `$`.
-   * do not use inline @see 
- * as spaces are used to mark code, the templates have very few indentation, thus they are awful to read (sorry)
- * `@example` 
-   * the sentence in the first line (next to the tag) is the title, it  must be enclose by double quotes 
-   * the following lines are the sample code. 
-   * 💔 since we simply hack the official tag, this syntax must be respected carefully 💔
-    
+   * do not reference variables since they are not documented. If you have to, always prefix them with `$`
  
+examples: 
+```
+/** 
+ * @see DBObject
+ * @see DBObject::Get()
+ * @see DBObject::$foo
+ */
+```   
 
-## dokuwiki requirements
- * the template uses the [wrap plugin](https://www.dokuwiki.org/plugin:wrap).
- * the generated files have to be placed under an arbitrary directory of `[/path/to/dokuwiki]/data/pages`.
- * the html has to be activated [config:htmlok](https://www.dokuwiki.org/config:htmlok)
- * the generated files have to be in lowercase
+#### Do not use inline tags, they do not work properly, example: 
+```
+/** 
+ * This is a texts with ans inline tag {@see [FQSEN] [<description>]} it must never be used 
+ */
+```
+   
+#### The `@example` tag must respect this very precise syntax 
+ * the sentence in the first line (next to the tag) is the title, it  must be enclose by double quotes 
+ * the following lines are the sample code. 
+ * 💔 since we simply hack the official tag, this syntax must be respected carefully 💔
+example: 
+```
+/** 
+* @example "This is the title of the multiline example"
+* $foo = DBObject::Get('foo');
+* DBObject::Set('foo', ++$foo);
+*/
+```  
+    
+## How content is included into the documentation
 
-## installation
+**For a class** those requirements have to be respected: 
+ - the file containing the class must be listed in `/phpdoc/files/file[]` of  `.doc/phpdoc-objects-manipulation.dist.xml`
+ - the class **must not** have the tag `@internal`
+ - the class **must** have at least one of: `@api`, `@api-advanced`, `@overwritable-hook`, `@extension-hook` 
+
+Then, **for a method** of an eligible class: 
+ - **public** methods **must** have at least one of: `@api`, `@api-advanced`, `@overwritable-hook`, `@extension-hook` 
+ - **protected** methods **must** have at least one of: `@overwritable-hook`, `@extension-hook` 
+ - **private** methods are **always excluded** 
+
+**Class properties** and **constants** are never documented (this is subject to change).
+
+
+
+
+## A note about the rendering engine
+  
+:notebook: as spaces are used to mark code, the templates (`.doc/phpdoc-templates/combodo-wiki/*`) have very few indentation, thus they are awful to read (sorry).
+
+
+
+
+## Installation
 ```
 composer require phpdocumentor/phpdocumentor:~2 --dev
 ```
 
-## bin
+## Generation
 `.doc/bin/build-doc-object-manipulation` and `.doc/bin/build-doc-extensions` contains examples of doc. generation, beware: they have to be called from iTop root directory:
 ```shell
 cd /path/to/itop/
 ./.doc/bin/build-doc-object-manipulation
 ``` 
 
-the resulting documentation is written into `data/phpdocumentor/output`
+the resulting documentation is written into `data/phpdocumentor/output`
+
+
+## Dokuwiki requirements
+ * the template uses the [wrap plugin](https://www.dokuwiki.org/plugin:wrap).
+ * the generated files have to be placed under an arbitrary directory of `[/path/to/dokuwiki]/data/pages`.
+ * the html has to be activated [config:htmlok](https://www.dokuwiki.org/config:htmlok)
+ * the generated files have to be in lowercase
+ 

.doc/phpdoc-templates/combodo-wiki/class.txt.twig

@@ -64,7 +64,7 @@
 
 {% include 'includes/see-also.txt.twig' with {structure:node, title_level: '==='} %}
 
-{% include 'includes/tags.txt.twig' with {structure:node, title_level: '=====', blacklist:  ['link', 'see', 'abstract', 'example', 'method', 'property', 'property-read', 'property-write', 'package', 'subpackage', 'phpdoc-tunning-exclude-inherited', 'api', 'api-advanced', 'overwritable-hook', 'extension-hook', 'copyright', 'license', 'code-example']} %}
+{% include 'includes/tags.txt.twig' with {structure:node, title_level: '=====', blacklist:  ['link', 'see', 'abstract', 'example', 'method', 'property', 'property-read', 'property-write', 'package', 'subpackage', 'phpdoc-tuning-exclude-inherited', 'api', 'api-advanced', 'overwritable-hook', 'extension-hook', 'copyright', 'license', 'code-example']} %}
 
 {% set methods = node.inheritedMethods.merge(node.methods.merge(node.magicMethods)) %}
 {% include 'includes/tag-synthesys.txt.twig' with {methods:methods, tag:'api'} %}
@@ -86,7 +86,7 @@
         or method.tags['extension-hook'] is defined
     )
     and (
-        node.tags['phpdoc-tunning-exclude-inherited'] is not defined
+        node.tags['phpdoc-tuning-exclude-inherited'] is not defined
         or method.parent.name == node.name
     )
 %}

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

@@ -47,7 +47,7 @@ you can extend the behaviour of iTop by implementing:
 {% endif %}
 {% set sanitizedMethod = method|trim('\\', 'left')|replace({(node.name~'::'): ''}) %}
 {% if '::' in sanitizedMethod -%}
-{%- if node.tags['phpdoc-tunning-exclude-inherited'] is not defined %}
+{%- if node.tags['phpdoc-tuning-exclude-inherited'] is not defined %}
   * [[{{sanitizedMethod|replace({'::': '#'})|lower}}|↪{{sanitizedMethod}}]] — {{  method.summary|replace({"\n":""})|raw }}
 {% endif %}
 {%- else %}

.doc/phpdoc-templates/combodo-wiki/interface.txt.twig

@@ -64,7 +64,7 @@
 
 {% include 'includes/see-also.txt.twig' with {structure:node, title_level: '==='} %}
 
-{% include 'includes/tags.txt.twig' with {structure:node, title_level: '=====', blacklist:  ['link', 'see', 'abstract', 'example', 'method', 'property', 'property-read', 'property-write', 'package', 'subpackage', 'phpdoc-tunning-exclude-inherited', 'api', 'api-advanced', 'overwritable-hook', 'extension-hook', 'copyright', 'license', 'code-example']} %}
+{% include 'includes/tags.txt.twig' with {structure:node, title_level: '=====', blacklist:  ['link', 'see', 'abstract', 'example', 'method', 'property', 'property-read', 'property-write', 'package', 'subpackage', 'phpdoc-tuning-exclude-inherited', 'api', 'api-advanced', 'overwritable-hook', 'extension-hook', 'copyright', 'license', 'code-example']} %}
 
 
 {% set methods = node.inheritedMethods.merge(node.methods) %}

core/dbobjectsearch.class.php

@@ -28,7 +28,7 @@ define('ENABLE_OPT', true);
  * Please refer to DBSearch's documentation
  *
  * @package     iTopORM
- * @phpdoc-tunning-exclude-inherited this tag prevent PHPdoc from displaying inherited methods. This is done in order to force the API doc. location into DBSearch only.
+ * @phpdoc-tuning-exclude-inherited this tag prevent PHPdoc from displaying inherited methods. This is done in order to force the API doc. location into DBSearch only.
  * @api
  * @see DBSearch
  * @see DBUnionSearch

core/dbunionsearch.class.php

@@ -29,7 +29,7 @@
  *
  *
  * @package     iTopORM
- * @phpdoc-tunning-exclude-inherited this tag prevent PHPdoc from displaying inherited methods. This is done in order to force the API doc. location into DBSearch only.
+ * @phpdoc-tuning-exclude-inherited this tag prevent PHPdoc from displaying inherited methods. This is done in order to force the API doc. location into DBSearch only.
  * @api
  * @see DBSearch
  * @see DBObjectSearch