Is there widely accepted phpDoc syntax for documenting which hook calls a function?

Question

Is there widely accepted phpDoc syntax for documenting which hook calls a function?

Curtis

2021年7月2日 12:03

I keep all hooks in one file, and the functions are organized in their respective classes (different auto-loaded files).

Looking for a standard way to document that a function's sole purpose is to be called on 'init' for example.

Currently using @see 'init'

Thanks!

Example Code

hooks.php

add_action( 'init', 'remove_image_sizes' );

functions.php

/**
  * Removes image sizes added by mistake prior to 1.6.18
  *
  * @since 1.6.18
  * @see 'init'
  * @return void
  */
function remove_image_sizes() {
  remove_image_size( 'foo' );
  remove_image_size( 'bar' );
}

Topic documentation plugin-development hooks theme-development Wordpress

Category Web

XedinUnknown · Accepted Answer · 2021年7月2日 12:03

Invoking a Hook

If you want to document the usage of a hook that you are invoking somewhere, i.e. things that hook handlers have to be aware of, then there is a hook documentation standard.

Using a Hook

If your function or method uses a hook, either by invoking or handling it, you can simply mention that with PHPDoc's standard syntax. This is because a WordPress hook is not a Structural Element that vanilla PHPDoc will look for. Let's look at the @see tag syntax:

@see [URI | FQSEN] [<description>]

This can be interpreted the following way:

The @see tag MUST be followed by a URI or the FQSEN, OPTIONALLY followed by the description. The URI and FQSEN components determine where the link points to, whereas the description component determines the text of the link.

Thus, a good way to document WP hooks used in your function is like this:

/**
 * Summary.
 *
 * @see https://developer.wordpress.org/reference/hooks/plugins_loaded/ plugins_loaded
 */
function myFunc() {}

Simon Kane · Accepted Answer · 2021年5月8日 10:01

I disagree with the previous answer. It appears that the respondent does not develop for WordPress: "Think of unit testing. In that context you are likely to call the function by itself" This, obviously, is not feasible for the overwhelming majority of WP code.

However, the "move the call" statement is, although infrequent because almost all hooks are designed to perform a very specific act, a valid concern. What is more typical is that an existing filter will end up being used by multiple hook IDs, as some of the IDs are dynamically generated, but statically referenced. The case where it is dynamic on both sides is beyond any kind of documentation parser's abilities.

I think the correct solution is something that parses add_action and add_filter calls into references of some kind like maybe @hook_for (I am just getting into this phpdoc stuff, so bear with me). This may be in a docblock, "special comment", or even just some kind of helper in doxygen or the like (but manual access is also needed to cover edge cases).

What I want is for doxygen or phpdoc to gather these @hook_for references into caller/callee lists like they do for normal function references - but obviously in a separate part of the output. Knowing which hooks a plugin or theme uses, and being able to 1-click to the code would be an amazing thing to have.

Now that I have invented a new "@" tag, hopefully someone will come along and say "that already exists - use this". I've looked at @see and @link, but not in depth -- maybe they are the answer? But, for the best results, we still need them to be auto-generated by something in the pre-processor (the add_filter/add_action parser I propose).

Mark Kaplun · Accepted Answer · 2018年2月15日 16:49

Function doc block should document what it does, what it might be useful for, but not who uses it. It makes sense to document that it was designed with hook X in mind but that is it.

Think of unit testing. In that context you are likely to call the function by itself without doing the whole core initialization, which means that a description tying the function to the init hook, will be at least misleading.

The style you are trying to use will also force you to change documentation while changing irrelevant code, like if you will decide to move the call to wp_loaded instead of init

Is there widely accepted phpDoc syntax for documenting which hook calls a function?

Example Code

Invoking a Hook

Using a Hook

About