Hook automatic documentation

[coquardcyr]

Hey,
Currently as a developer the experience about searching hooks on an installed plugin is a pain.

First when picking a new plugin on the marketplace nothing indicates to me if the plugin makes use of actions or filters to configure it to my needs.
The only way to know is to download the plugin then open it in my IDE and each for each occurrence from the method apply_filters and do_action.

Then once the plugin is installed and I am using a filter or an action, it is not finished if there is an update and I want to make sure the developer from the plugin didn't remove or change the plugin. I need to jump again into the code and make sure hooks weren't touched.

My idea to tackle that would be simple.
On one hand I think this documentation is important for end users but on another one I don't want to make plugins developers waste a bunch of more time on it.

That's why automation seems the good way to me as it will allow developers to be able to provide that in one command in the cli.

To reduce the amount of memory that would be used on wordpress.org by that feature I would split it into two parts linked with a file as an interface between them describing hooks.
Moreover the choice of a separation between the tools to make an interface which leaves room for other tools in the future as an IDE plugin and it also gives the opportunity for the developer to change the file generated in case there is an issue with the cli command.

So for that feature we would have a cli command that generates a file describing the hooks from the plugins and another part about displaying information about hooks on the marketplace from wordpress.org using that file.

For that cli part,I already started something here with my custom framework that could be seen as a poc: ​https://github.com/wp-launchpad/hooks-extractor
However, it is based on regex and it seems like it has a lot of flaws so there is still room for improvement.
For example, I guess another approach based on a tokenizer would work better.

Concerning the generated documentation I got that repository which is not really related to the second part: ​https://github.com/wp-launchpad/hook-list

Nevertheless it generates a small documentation from a yaml file which can be useful to display some information to the end user.

The idea for that second part would be to have a list of hooks and their documentation for each plugin when the file is detected. This would also promote the usage from hooks through the community as they are not that much common.

Then that file would also be reused inside the changelog to add hooks changes.

Finally, it would be nice to have a way to filter on the marketplace between plugins that support that feature and the one who don’t as it will promote that practice even more

As you can see there is a lot of room for improvement for that feature and I am not only accepting feedback about if this feature could be something good to the WordPress ecosystem but also suggestions to improve it.

[flexseth]

The Genesis Framework had a Visual Hooks plugin that was very helpful back in the day
​Genesis Visual Hooks Guide

For WooCommerce
​WooCommerce Visual Hook Guide

Maybe to incentivize contributors who want to get into the directory and have priority, they could provide a similar functionality that would allow theme authors and developers to extend and design on their software more easily and visually.

Or even making this a requirement if hooks are included.

Using PHP Doc Blocks (think this is the terminology) could automate this, I think.

Still new to the documentation thing :)

[coquardcyr]

Hey @flexseth,

Effectively not visualizing hooks is something so common to me I also started to take it for granted.
However, you are totally right being able to know where visual hooks fire in the page is time saving.

Also a way to implement that could be like in Joomla where they display hooks when a certain parameter is passed. (Maybe we could activate that feature only when the user is connected as an admin to prevent leaking information about the website)

The only potential issue I see with that is how to recognize a hook is visual as I think if we apply it to every hooks then it could lead to some issues due to that we will display content before we should have.

[flexseth]

The only potential issue I see with that is how to recognize a hook is visual

@coquardcyr - in the PHP Standards docs there are best practices for hooks that display information.

Functions: What does the function do?
Good: Displays the last modified date for a post.

​Link to docs

So a well documented hook would look something like this:

<?php
/**
 *
 * my_awesome_plugin_before_title_hook
 *
 * Description: Displays content before the post title
 *
 * @version 1.0.2
 * @return  string
 *
 */
add_action( 'my_awesome_plugin_before_title_hook', 'post_title' );
function my_awesome_plugin_before_title_hook() {
  return {
    // HTML to output
  }
}

If visual hooks were standardized and linted before passing the (already rigorous) plugin guidelines for review, it would be easy to build a plugin for display only hooks.

IMO: With many new people coming into WordPress this could be a great improvement. Imagine someone wants to add a "Like" button to a certain part of the page. They can set this up on Facebook, but don't exactly know how to do it.

But there's an easy to use plugin boilerplate, and documented display hooks.

They could roll a plugin, add the hook, and enter the code (usually JavaScript)

Instantly a developer :)

This code is meant to represent pseudocode-ish and not functional code

[dd32]

For the vast majority of WordPress users, unfortunately I don't think the effort of adding automatic hook documentation for plugins is going to be overly useful.

As I'm sure most will know, most plugins don't include any hooks of use at all, and when they do, often they're incorrect or not totally usable.

Plugins can choose to document their existing hooks in their readme, or on their support site already. I'm aware of a few who do.

See also: #3126 (List WP-CLI commands), and that the plugins page lists Blocks that the plugin includes (But this is partially because we needed a way to find a plugin by a specific block slug IIRC)

That all being said; We already have a hook documentation extractor that we'd use for this, if we chose to do it. What's used for developer.wordpress.org extractions from Core ​https://github.com/WordPress/phpdoc-parser