I have an issue trying to exclude single files, using the --exclude argument

It works fine when I exclude a whole folder, yet I just want to exclude one file. It seems to ignore the --exclude statement, if I pass a valid filename, but it works when I pass a valid folder name.

Example: --exclude=foldername => works (excludes whole foldername folder) --exclude=filename.php => fails (does not exclude that file)

I have also tried with foldername/filename and different other syntax, inclusive brackets, and it just seems to ignore it when the name passed is not a folder.

According the description however it seems it should be possible to exclude single files? Even better would be to exclude occurrences it cannot parse and just skip. I have a peculiar plugin that does something like this: do_action( $atts['hook_name'] );

Of course, that hook fails in the parser with these errors:

Not supported hook tag expression `PhpParser\Node\Expr\ArrayDimFetch`: $att  
  s['hook_name'].   
Could not convert tag argument value to a name in path/to/file/filename.php#N. 

This is why I want to exclude that file, but of course if there's an easy way to just skip when failing, instead of halting, that would be the best!

Happens that sometimes a codebase does apply_filters or do_action the same hook more than once. With the current template, you then get a DOC with each instance of that apply_filters or do_action repeated as many times as the codebase uses it.

For example, if you use a apply_filters( 'list_cats', $r['show_option_all'], null ) more than once (WP does that), your doc would result in a list of several list_cats, instead of just one, but you'd not want that.

With the proposed change, the filter or action, if already printed, will be skipped. It might not be the best solution but avoids n-plicated occurrences of the same filter/action

NOTE The template as such for me was not functional, I had to make changes to get it working, but those changes I will provide in another PR (if that's OK)

Add support for the @ignore tag:

• https://github.com/pronamic/wp-documentor/issues/13

Also see:

• https://docs.phpdoc.org/guide/references/phpdoc/tags/ignore.html
• https://pear.php.net/package/PhpDocumentor/docs/latest/phpDocumentor/tutorial_tags.ignore.pkg.html

@ignore

The @ignore tag is used to tell phpDocumentor that Structural Elements are not to be processed by phpDocumentor.

Syntax

@ignore [<description>]

A new --prefix option will allow limiting the output to hooks matching the prefixes passed as a comma-separated list. For example, --prefix=my_theme,my_plugin would include my_theme_some_hook and my_plugin_some_other_hook but exclude not_my_hook from the output.

This can be useful when developers need to document the proprietary action and filter hooks introduced by their theme or plugin.

There seems to be a difference in the output between the two following occurrences:

<?php
/**
 * My plugin filter assigned to a variable
 *
 * @param string $first_param This is the first argument
 * @param string $second_param This is the second argument
 */
$some_variable = apply_filters( 'my_plugin_filter', $first_param, $second_param );

return $some_variable;

<?php
/**
 * My plugin filter directly returned
 *
 * @param string $first_param This is the first argument
 * @param string $second_param This is the second argument
 */
return apply_filters( 'my_plugin_filter', $first_param, $second_param );

In the first case, the full list of arguments is correctly parsed. In the second case, the list of arguments is empty.

I think we as developers should be able to add something to the phpdoc of a hook to let wp-documentor know that it should NOT be documented. This is because some applications enqueue hooks so dynamic that it has no value.

Maybe something like this?

/**
 * @ignore
 */
$result = apply_filters($hook, $queue, $parameter);

edit: this could also be handy when using the result of native WP hooks in your project, such as https://developer.wordpress.org/reference/hooks/the_content/

Currently the @link tags are not rendered in the markdown template.

/**
 * Prints scripts or data in the head tag on the Adyen checkout page.
 * 
 * This action can be used, for example, to register and print a custom style.
 *
 * See the following link for an example:
 * https://github.com/wp-pay-gateways/adyen#pronamic_pay_adyen_checkout_head
 *
 * @link https://github.com/WordPress/WordPress/blob/5.7/wp-includes/general-template.php#L3004-L3009
 *
 * @since 1.1
 */
do_action( 'pronamic_pay_adyen_checkout_head' );

https://github.com/wp-pay-gateways/adyen/blob/62425e3706d32c63697cd31dbd57ba0894a60118/views/head.php#L8-L19

https://github.com/wp-pay-gateways/adyen/blob/develop/docs/hooks.md#pronamic_pay_adyen_checkout_head

bin/wp-documentor parse wordpress --format=markdown --type=actions --relative=tests/docs --memory-limit=-1 --output=tests/docs/wordpress-actions.md

bin/wp-documentor parse wordpress --format=markdown --type=filters --relative=tests/docs --memory-limit=-1 --output=tests/docs/wordpress-filters.md