How should I document function calls?

by

You don’t document function calls, but function definitions. Because the function could be called unlimited times, right? So it makes no sense to document functions when they are called.

If you document the call, then probably because you do some things you want to remember later – or let other following developers know. But normally, I would say, that shouldn’t happen – in a perfect world.

Now the hook system is somewhat different from normal calls, which might be the reason for the confusion. But actually it isn’t, the function add_action() itself is documented, so it is about the hook and the function used. Lets look at your example:

add_action( 'foo', 'bar' );

Where foo is the hook and bar is the function. For this you probably have to go at it like @birgire shows it in his answer.

I’m assuming you know how to document the function, you linked the correct document. There you find two sections about documenting hooks too, which does apparently only apply to do_action() and apply_filters().

    /**
     * Summary.
     *
     * Description.
     *
     * @since x.x.x
     *
     * @param type  $var Description.
     * @param array $args {
     *     Short description about this hash.
     *
     *     @type type $var Description.
     *     @type type $var Description.
     * }
     * @param type  $var Description.
     */

/** This action is documented in path/to/filename.php */

This is the official part.

Personally like to add something like this:

/**
 * (Here is the official part)
 *
 * @hooked bar - 10
 */
do_action( 'foo' );

I do this on the finishing touches of a project, because I find it somewhat helpful and informational. I did not come up with that, but don’t ask me where it is from, might be from WC. Additionally I’d like to note that it is probably not good practice. The schema here is

@hooked function_name - priority

Leave a Comment