Document WordPress filters and actions

[remcotolsma]

WooCoomerce

WooCoomerce is using a PHP script to document their WordPress filters and actions:
https://github.com/woocommerce/code-reference/blob/0.7.0/generate-hook-docs.php

It extends https://www.phpdoc.org/ documentation by replacing the text <!-- hooks --> in the generated phpDocumentor output files: https://github.com/woocommerce/code-reference/blob/0.7.0/generate-hook-docs.php#L333.

https://woocommerce.github.io/code-reference/

ApiGen

Before June 2019, WooCommerce used ApiGen:
https://github.com/woocommerce/woocommerce/pull/24003/files

The ApiGen documentation was removed somewhere between WooCommerce version 3.6.0 and 3.7.0: https://github.com/woocommerce/woocommerce/tree/3.6.0/apigen. This documentation was also extended with the hooks / actions information via a PHP script: https://github.com/woocommerce/woocommerce/blob/3.6.0/apigen/hook-docs.php. It also had a "Direct known implementers" and "Indirect known implementers" sections, which are not yet available in the phpDocumentor documentation: woocommerce/code-reference#11.

WP Parser

The WordPress Code Reference on https://developer.wordpress.org/reference/ is generated using https://github.com/WordPress/phpdoc-parser, more information about this can be found at https://make.wordpress.org/docs/handbook/devhub/. This libary/plugin contains WP-CLI commands to export PHPDoc markup to JSON and convert it into WordPress posts, and insert into DB.

WordPress HookDoc

An alternative is to use https://github.com/matzeeable/wp-hookdoc which uses https://github.com/jsdoc/jsdoc.

GitHub Actions for WordPress

In https://github.com/10up/actions-wordpress#ideas the following idea is described:

Generate hook docs into a Markdown file that can be published into a subfolder, GitHub wiki, and/or gh-pages branch.

This idea was added by @helen almost 2 years ago:
10up/actions-wordpress@556d7a6

Update April 4, 2021

This idea has already been realized, see:
https://github.com/10up/actions-wordpress/blob/stable/hookdocs-workflow.md

Example

• https://github.com/10up/distributor/blob/develop/.github/workflows/build-docs.yml
• https://10up.github.io/distributor/

Hookster

Thinking about making a developer docs website for your WordPress theme or plugin? For my weekend project, I made a build script for theme/plugin authors to automatically generate data about all the actions and filters of their product.

https://twitter.com/jasonbobich/status/987836700989669376

https://github.com/themeblvd/hookster

Yoast Parser

• phpDocumentor / Reflection » Issue "Extracting WordPress hooks from source"
• Gist » jcomack/FileVisitor.php
• https://github.com/Yoast/code-documentation-extractor

phpDox

https://phpdox.net/

Other Plugins

There are also many other plugins that have documentation for their filters and actions:

• Gravity Forms
• Advanced Custom Fields
• Easy Digital Downloads
• WPForms
• Posts 2 Posts
• Breadcrumb NavXT
• BuddyPress
• bbPress

[helen]

Hi! Looks like I need to update the develop branch but we do have hook docs via GH Actions working! https://github.com/10up/actions-wordpress/blob/stable/hookdocs-workflow.md

[remcotolsma]

We developed https://github.com/pronamic/wp-documentor for this, see as output: https://github.com/wp-pay/core/blob/develop/docs/hooks.md.

@helen maybe is https://github.com/pronamic/wp-documentor also something for 10up 😊? The advantages of https://github.com/pronamic/wp-documentor are that you do not have to add the @hook tag or put the types between curly brackets (for example: {int}, {string}, etc.).