Developer doc: script to auto generate list of available hooks in piwik

[mattab]

The goal is to provide a documentation listing the hooks that plugin developers can use to enhance Piwik.
Each hook would be listed with the name, and a quick documentation of the parameters and data array (if any).

Tasks to do:
- decide on a naming convention for naming the hooks in Piwik #613
- how could we auto generate the documentation for the hooks? Example of [drupal list of hooks](http://api.drupal.org/api/group/hooks/6)
- Also provide a sample list of the hooks triggered
– on the dashboard homepage
– in a widget
– during archiving
This could be done by adding logging in the plugin hook handling code.

[robocoder]

duped in #613

[mattab]

Not a critical doc to have, but would be nice for sure.

[mattab]

This could be maybe done as ant task in the build on the continuous build server piwik.org/qa/ ?

[mattab]

Maybe this could be done, by tagging the Hooks with a special PHP-doc tag, and then have phpdoc generate a doc for all the tags found... plus show the actual string of the event name in the code...

[robocoder]

Would need a preprocessor as there's no existing doc tag to support this.

I'm looking at using a preprocessor for piwik.js, so might tackle this at the same time.

[mattab]

Cool vipsoft. I think a simple list of All hooks with a description (put in the comment), file & line number hook is sent from. This would be a good add to http://piwik.org/docs/plugins/

[robocoder]

FYI

In Drupal, hooks are documented in dummy source files. They follow a convention where files are named modulename.api.php, and contain:

/**
 * phpdoc comments
 */
function hook_my_hook_name($parameters, ...) {
    /* example code */
}

WordPress hooks lack phpdocs and the same hook may be triggered in multiple places. To generate docs, one could grep for occurrences of:

do_action( 'the_hook_name', $parameters, ... );

[mattab]

Implemented :)

The list of events in Piwik is automatically generated at: http://developer.piwik.org/api-reference/events

If you have feedback or suggestion please comment!