From 22416cc0be677ce26518018f5163153a68364054 Mon Sep 17 00:00:00 2001 From: bruno DA SILVA Date: Fri, 24 May 2019 14:05:22 +0200 Subject: [PATCH] :note: PhpDoc generation for the public API - typo (tunning => tuning) - rework of the README.md --- .doc/README.md | 105 +++++++++++++----- .../combodo-wiki/class.txt.twig | 4 +- .../includes/tag-synthesys.txt.twig | 2 +- .../combodo-wiki/interface.txt.twig | 2 +- core/dbobjectsearch.class.php | 2 +- core/dbunionsearch.class.php | 2 +- 6 files changed, 84 insertions(+), 33 deletions(-) diff --git a/.doc/README.md b/.doc/README.md index 4fc2df2df..50a0769df 100644 --- a/.doc/README.md +++ b/.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] []} 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` \ No newline at end of file +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 + diff --git a/.doc/phpdoc-templates/combodo-wiki/class.txt.twig b/.doc/phpdoc-templates/combodo-wiki/class.txt.twig index 94e805173..5959eff9f 100644 --- a/.doc/phpdoc-templates/combodo-wiki/class.txt.twig +++ b/.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 ) %} diff --git a/.doc/phpdoc-templates/combodo-wiki/includes/tag-synthesys.txt.twig b/.doc/phpdoc-templates/combodo-wiki/includes/tag-synthesys.txt.twig index 05b26087a..1c68b90b1 100644 --- a/.doc/phpdoc-templates/combodo-wiki/includes/tag-synthesys.txt.twig +++ b/.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 %} diff --git a/.doc/phpdoc-templates/combodo-wiki/interface.txt.twig b/.doc/phpdoc-templates/combodo-wiki/interface.txt.twig index 5bf639994..2f8d0698c 100644 --- a/.doc/phpdoc-templates/combodo-wiki/interface.txt.twig +++ b/.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) %} diff --git a/core/dbobjectsearch.class.php b/core/dbobjectsearch.class.php index 002c643d8..9d4e1755c 100644 --- a/core/dbobjectsearch.class.php +++ b/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 diff --git a/core/dbunionsearch.class.php b/core/dbunionsearch.class.php index dada399a9..01a0e2a8b 100644 --- a/core/dbunionsearch.class.php +++ b/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