[wp-trac] [WordPress Trac] #35974: `@param` tags with `&` in variable names are not parsed as parameters in the developer docs

[WordPress Trac]

#35974: `@param` tags with `&` in variable names are not parsed as parameters in
the developer docs
--------------------------+-----------------------
 Reporter:  sudar         |       Owner:
     Type:  defect (bug)  |      Status:  reopened
 Priority:  normal        |   Milestone:  4.9
Component:  General       |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  needs-patch   |     Focuses:  docs
--------------------------+-----------------------
Changes (by johnbillion):

 * keywords:  has-patch => needs-patch
 * status:  closed => reopened
 * resolution:  worksforme =>
 * milestone:   => 4.9


Comment:

 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.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/35974#comment:11>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform