`@param` tags with `&` in varaible names are not parsed as parameters

[sudar]

I originally reported it in WordPress core trac 35974

Below is the summary of the issue.

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.

[JDGrimes]

I did a little digging into this, and it is ultimately an issue with the syntax in question not being supported by phpDocumentor\Reflection\DocBlock. As far as I can tell, this syntax is simply not part of the phpDocumentor standard. Of course, it would be possible for us to reparse the docblock content to handle this however we want, but I just want to be clear that this doesn't appear to be "standard".

[GaryJones]

This appears to be an upstream issue: https://github.com/phpDocumentor/ReflectionDocBlock/blob/master/src/DocBlock/Tags/Param.php#L79

[johnbillion]

Hopefully all of these instances have now been removed from core. See https://core.trac.wordpress.org/ticket/35974.