[wp-hackers] Hook (Filter, Action) Documentation Idea

[hakre]

While I've be doing a lot of work related to hooks in wordpress lately, the 
following idea came into my mind:

To create a PHP file that contains functions for documentation purposes 
containing all hook names as function names.

The hooks name is defined by using it as function name. If the hook contains 
variable parts, they should be replaced with a uppercase marker (hook names are 
all lower case), like VARY or similar.

The hooks parameter can be specified by defining them in the function header.

Meta Information can be provided via docblock comments.

Such a file can be easily parsed with the PHP Reflection classes as well as with 
tools like phpdocumentor to render stuff out.

Example:

/**
 * Pre Option Filter
 *
 * Description
 *
 * @since 1.5.0
 * @-wp-type  filter
 * @-wp-vary option name
 * @param mixed $value option value
 */
function pre_site_option_VARY($value) {
}

It might be an even better idea to create a class and put all functions inside. 
Might be easier to test against and can be included even in running applications 
w/o much fuzz.

Such a file can be added to version control and kept in line with the main code.

Feedback appreceated.

-- hakre

 http://hakre.wordpress.com/