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

[Jacob Santos]

I went around and around with a lot of ideas with hook documentation. In my
opinion, I believe a specialized phpdoc type tag would be better. The
problem is that someone would have to 1) go through each function, method
and document the filters and actions and 2) would have to write a
specialized parser for this new phpdoc type tag. Since phpdocumentor does
not use them, it will have to be a new site.

The problem with your idea, is that not only will it be required that new
functions or methods (empty, sure) have to be created, but also documented.
There being over 100 filters and actions (more like 300-400 last time I
checked, but unsure), that is quite a lot of work. You'd also have to go
back and add @uses information for those fake hook functions or methods.

In your example, there will still need to be a new parser created.

In the end, I just went with @uses apply_filters and @uses do_action to
describe the actions and filters. Not that it is the best way to do it, but
it works in phpDocumentor and people can still get the information.

Problem is, that any way to go about solving this will require a lot of work
and it will require someone willing to do so. Whoever that person is,
whatever they decide, I believe, is good enough for me.

Jacob Santos

On Wed, Sep 8, 2010 at 11:36 AM, hakre <hanskrentel at yahoo.de> wrote:

> 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/
>
>
>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>