Automatically generate PHP Source code documentation for developers (classes, methods)

[mattab]

Piwik core contains a significant amount of classes. Many of these are used in several places in core and plugins and will be used by plugin developers.

The goal of this ticket is to provide Piwik Plugin developers with a great documentation about the classes and methods which are most useful to them when making plugins.

This ticket focus is on deciding which parts of the code (classes, methods) are useful to other developers.

• typical classes that will be used by devs include Url, UrlHelper, DataTable, Date, Db, Http, Ip, Log, ...
• Maybe we use a custom phpdoc annotation, which could be picked up by phpdoc to autogenerate our public API documentation. eg. @framework or @platform or @UseIT ....
• annotation could be set on the class (in which case all public methods' docs would be generated), or the tag could be set on specific methods (in case other public methods would not really useful to plugin devs) <- limits noise & need to write docs
• docs ideally would be generated in markdown so we could integrate within marketplace and/or piwik.org website easily (if this can be done with phpdoc)
• automated on Travis CI when the build was green (alternatively we put a cron on piwik.org)

At the end we should have auto generated doc which developers can easily use when they need something already implemented in Piwik.

[tsteur]

The @api seems to be appropriate: http://www.phpdoc.org/docs/latest/for-users/phpdoc/tags/api.html

[tsteur]

In c94adb6: refs #4194 marked some classes and methods as API to test doc generation

[tsteur]

In 29c57ee: refs #4194 marked some classes/methods/functions as available for plugins

[tsteur]

In b061d3a: refs #4194 ignore console commands

[tsteur]

In 6aa7ab6: refs #4194 the api ignore tag is not needed, we simply ignore all symfony commands in the api generator

[tsteur]

In 461df89: refs #4194 marked some more classes as api

[tsteur]

Closing this now. Documentation generator is located here: https://github.com/piwik/pluginapi-doc-generator/

Follow up tickets created: #4200 #4201