iTop/.doc/README.md

phpdoc dokuwiki template

This directory contains a template rendering iTop phpdoc as wiki pages.

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.

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())
  • 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 💔

dokuwiki requirements

• the template uses the wrap plugin.
• 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
• the generated files have to be in lowercase

installation

composer require phpdocumentor/phpdocumentor:~2 --dev

bin

.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:

cd /path/to/itop/
./.doc/bin/build-doc-object-manipulation

the resulting documentation is written into data/phpdocumentor/output