README

WordPress Doc Generator is a tool to automatically extract data about the actions, filters and shortcodes of your WordPress theme or plugin.

Table of contents

• Getting Started
• Command Line Usage
• Notes
• Alternatives
• Links

Getting Started

Installation

Install it with composer

composer require dudo1985/wpdocgen --dev

Command Line Usage

First parameter is the input directory, second is the output file, e.g.

vendor/bin/wp-doc-gen . hooks.md

This will parse all the files in the current directory (.) and write a file called hooks.md

Optional params

--shortcodes or -s

By default, WPDocGen search for hooks apply_filters and do_actions. However, if you use the --shortcodes or -s will search for add_shortcode function instead.

vendor/bin/wp-doc-gen . shortcodes.md -s

--exclude or -e

Exclude the specified folders, e.g.

vendor/bin/wp-doc-gen . hooks.md --exclude vendor node_modules

Another example, if you're launching the script from another dir:

vendor bin/wp-doc-gen.php ../my-plugin/ docs/hooks.md --exclude vendor node_modules --prefix yasr

There is no need to include the full paths of the excluded dirs, it is automatically ../my-plugin/vendor and ../my-plugin/node_modules

--prefix or -p

Only parse hooks or shortcodes starting with the specified prefixes.

vendor/bin/wp-doc-gen . hooks.md --exclude vendor node_modules --prefix prefix_1 prefix_2

--verbose or -v

More detailed error messages.

--version or -V

Print the version number

Real life Examples

Generated markdown files

• https://github.com/Dudo1985/Yet-Another-Stars-Rating/blob/master/docs/yasr_hooks.md
• https://github.com/Dudo1985/Yet-Another-Stars-Rating/blob/master/docs/yasr_shortcodes.md

Composer script

• How I use it into composer

Notes

To make the parser work fine, the comment must be a valid phpDocBlock, e.g.

/**
* Use this action to add tabs inside shortcode creator for tinymce
*/
do_action('yasr_add_tabs_on_tinypopupform');

will generate this code

do_action('yasr_add_tabs_on_tinypopupform')

Source: ../yet-another-stars-rating/admin/editor/YasrEditorHooks.php, line 219

Use this action to add tabs inside shortcode creator for tinymce

or, another example with tags

/**
* Use this action to add content inside shortcode creator
*
* @param int $n_multi_set
* @param string $multi_set the multiset name
*/
do_action('yasr_add_content_on_tinypopupform', $n_multi_set, $multi_set);

will generate this code with table

do_action('yasr_add_content_on_tinypopupform')

Source: ../yet-another-stars-rating/admin/editor/YasrEditorHooks.php, line 235

Use this action to add content inside shortcode creator

| Argument     | Type   | Description       |
|--------------|--------|-------------------|
| $n_multi_set | int    |                   |
| $multi_set   | string | the multiset name |

But, if you use the type after the argument, e.g.

/**
* @param $n_multi_set int
*/

this will insert the type (int and string in this example) inside the "Description" column:

| Argument     | Type | Description              |
|--------------|------|--------------------------|
| $n_multi_set |      | int                      |

Alternatives

Here is a list of alternatives that I found. However, none of these satisfied my needs

• WP Documentor by Pronamic | This is the project that I used for a while, but I needed something to best fit my needs. The following list comes from their readme

• WP Parser by WordPress

• Hookster by Theme Blvd

• WordPress HookDoc by Matthias Günter

• GitHub Actions for WordPress by 10up

• Yoast Parser by Yoast

• WooCommerce Code Reference Generator by WooCommerce

• WordPress Hooks Reference by John Blackbourn / Human Made

• wp-hooks-generator by John Blackbourn / Human Made

Links

• https://developer.wordpress.org/plugins/hooks/
• https://developer.wordpress.org/plugins/hooks/actions/
• https://developer.wordpress.org/reference/functions/do_action/
• https://developer.wordpress.org/reference/functions/add_action/
• https://developer.wordpress.org/plugins/hooks/filters/
• https://developer.wordpress.org/reference/functions/apply_filters/
• https://developer.wordpress.org/reference/functions/add_filter/
• https://developer.wordpress.org/reference/hooks/
• https://developer.wordpress.org/reference/functions/add_shortcode/
• https://www.phpdoc.org/
• https://github.com/phpdocumentor/phpdocumentor