phpdoc-parser

phpdoc-parser copied to clipboard

This might be outside the intended scope of this plugin, but I hope it will be considered anyway.

Let's take a basic action of a theme calling do_action( 'wp_head' ). Parsing the theme, this makes it look like the hook originated in this theme, when really it is defined elsewhere (in WP itself).

For those generating docs specifically for a plugin or theme, it might make sense to be able to add a tag (@externalhook?) to the hooks documentation that identifies that a hook originates outside of the source being parsed (and so ignore those hooks like how @internal works).

A child theme might do the same with hooks that are originally defined in the parent theme.

Also ping @drewapicture - any thoughts on something like this being suitable for a wider recommendation via the Handbook?

/**
 * @externalhook
 */
do_action( 'wp_head' );

I think having a way to designate a hook's origin, even if that means just saying, "it didn't originate 'here'" is probably a good idea. I think that could also be applied even for the bundled default themes that have their own hooks for things.

Not sure about the best way to do that. I'm not a super big fan of introducing a custom tag just for that though. Is there any kind of "origin" tag precedent in place with the phpDoc spec?

There's an @ignore tag supported by phpDocumentor (and maybe other DGAs) which would be most suitable, but it's not referenced in the pull request for the work-in-progress PSR-5.

The format for custom tag names is @{vendor}-{tag name}. The @wordpress-plugin tag for instance is in use, as it's part of the WP Plugin Boilerplate. As such, we'd need to introduce it as @wordpress-externalhook or something similar, rather than just @externalhook.

The ANBF for tag names is: (ALPHA / "\") *(ALPHA / DIGIT / "\" / "-" / "_"), so we could write is as @wordpress-external-hook, @wordpress-external_hook or even @wordpress-ignore, the latter indicating that the hook docs should be ignored for whatever reason (the hook is external, the hook is a duplicate which is defined elsewhere (this source, or another)). Docs for other structural elements could be ignored too, without necessarily indicating that it is @deprecated or just @internal.

Let's take a basic action of a theme calling do_action( 'wp_head' ). Parsing the theme, this makes it look like the hook originated in this theme, when really it is defined elsewhere (in WP itself).

I'm not quite sure what you mean by this?

I think if we did go ahead with a custom hook, I'd prefer the shorthand wp-external version. This because I anticipate eventually incorporating other custom tags in the future and "wordpress" can get verbose pretty quick.

On Mon, Feb 10, 2014 at 7:03 PM, Gary Jones [email protected]:

There's an @ignore taghttp://phpdoc.org/docs/latest/references/phpdoc/tags/ignore.htmlsupported by phpDocumentor (and maybe other DGAs) which would be most suitable, but it's not referenced in the pull requesthttps://github.com/php-fig/fig-standards/pull/169/filesfor the work-in-progress PSR-5.

The formathttps://github.com/php-fig/fig-standards/pull/169/files#diff-9a10a11696dc38209c125ea9c57a565fR408for custom tag names is @{vendor}-{tag name}. The @wordpress-plugin tag for instance is in use, as it's part of the WP Plugin Boilerplate. As such, we'd need to introduce it as @wordpress-externalhook or something similar, rather than just @externalhook.

The ANBF for tag names is: (ALPHA / "") *(ALPHA / DIGIT / "" / "-" / "_"), so we could write is as @wordpress-external-hook, @wordpress-external_hook or even @wordpress-ignore, the latter indicating that the hook docs should be ignored for whatever reason (the hook is external, the hook is a duplicate which is defined elsewhere (this source, or another)).

Reply to this email directly or view it on GitHubhttps://github.com/rmccue/WP-Parser/issues/45#issuecomment-34719897 .

[image: Drew Jaynes's Visual Thumbprint]https://www.vizify.com/es/50d2d406cdea0c0012000281 -- I've kinda got a thing for WordPress > http://www.drewapicture.com

The vendor name, lowercase, would be wordpress - it shouldn't be abbreviated. That's why annotations for Symfony or Doctrine use the full Symfony or Doctrine word, even though SF would be the common abbreviation for Symfony. There's shouldn't be any possible clash with some other project that's abbreviated to wp out there, if they happened to add custom tags. (It's why I hate WordPress plugins using function prefixes or textdomains with abbreviations - clarity is better than a few saved bytes.)

I'm not quite sure what you mean by this?

It's trying to limit the documentation to hooks defined at the intended source level, and not those that originate in the parent source. i.e. if I'm parsing Genesis, I only want to include the Genesis hooks, and not those from WP that Genesis uses to make it play nice with others.

From technical point of view I am not sure "origin" of hook makes sense for me. What is of interest are hook invocations and additions of things to it, neither necessarily in singular place or confines of same code base.

If third party code calls "core" hook I would want to know about it.

I think in this form this seems like question for core documentation effort. So far parser is too buried in "primary" issues (that is actually working for DevHub use case), scanning third party code will have to wait for its turn. I hope it doesn't sound dismissive, honestly there is just only so much I can sign up for myself and my agenda here is getting DevHub ticking.

I understand that DevHub needs comes first - it would just be really nice to be able to use v1 on third-party code too.

I guess my logic is to be able to answer the question: "I'm a Genesis child theme developer - I know what hooks WP core has, but what extra ones does Genesis provide me?"