`@param` tags with `&` in variable names are not parsed as parameters in the developer docs

[sudar]

While documenting hooks, if & is added in the @param tag, then they are not regonized as parameters in the developer docs.

Eg: Look under parameter sub-heading in the following pages

​https://developer.wordpress.org/reference/hooks/http_api_curl/
​https://developer.wordpress.org/reference/hooks/posts_where/

and about a dozen pages where the parameters are not documented properly.

I did a full search in the code base for the regex 'param .* \&\$' and fixed those instances.

The patch I am attaching doesn't have any code changes. It only fixes phpdocs for the hooks who's parameters are not documented properly.

[swissspidy]

I think we should rather fix the parser instead of making the docs "incorrect". What do you think, @DrewAPicture?

[DrewAPicture]

Replying to swissspidy:

I think we should rather fix the parser instead of making the docs "incorrect". What do you think, @DrewAPicture?

Yeah, we should just fix the parser to recognize variables passed by reference.

@sudar If you're interested in helping add compatibility, development for the official parser happens on GitHub: ​https://github.com/WordPress/phpdoc-parser

[sudar]

Didn't realize that phpdoc standard expects the &.

Will try to see if I can find a way to fix the phpdocs-parser.

[swissspidy]

Looks like it's working now.

[pcarvalho]

i'm still seeing the params formatted wrong.

​https://developer.wordpress.org/reference/hooks/the_posts/

reopen?

[johnbillion]

Thanks for pointing this out, @pcarvalho. I've opened a meta ticket to get this fixed in the parser: ​#META3171.

[johnbillion]

Re-opening as I think we need to address this in core.

As @garyj points out on ​https://github.com/WordPress/phpdoc-parser/issues/176, a leading & symbol isn't actually a supported notation in phpDocumentor's docblock syntax. They should be removed from the documentation.

There are actually several places in core where variables passed by reference aren't documented with a preceding & symbol. For example https://core.trac.wordpress.org/browser/tags/4.8.2/src/wp-admin/includes/credits.php?marks=63,65#L56.

[johnbillion]

In 41686:

Docs: Remove & prefixes from parameter documentation to avoid doc parsing errors.

Props sudar for the original patch.

See #35974

[johnbillion]

In 41688:

Docs: Standardise the format used for documenting parameters passed by reference.

See #35974, #41017