Opened 7 years ago
Closed 6 years ago
#35974 closed defect (bug) (fixed)
`@param` tags with `&` in variable names are not parsed as parameters in the developer docs
Reported by: |
|
Owned by: | |
---|---|---|---|
Milestone: | 4.9 | Priority: | normal |
Severity: | normal | Version: | |
Component: | General | Keywords: | needs-patch |
Focuses: | docs | Cc: |
Description
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.
Attachments (1)
Change History (15)
#3
in reply to:
↑ 2
@
7 years ago
- Milestone changed from Awaiting Review to WordPress.org
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
#4
@
7 years ago
Didn't realize that phpdoc standard expects the &
.
Will try to see if I can find a way to fix the phpdocs-parser.
#5
@
7 years ago
- Summary changed from `@param` tags with `&` in varaible names are not parsed as parameters in the developer docs to `@param` tags with `&` in variable names are not parsed as parameters in the developer docs
#7
@
6 years ago
- Milestone WordPress.org deleted
- Resolution set to worksforme
- Status changed from new to closed
Looks like it's working now.
This ticket was mentioned in Slack in #core-docs by pcarvalho. View the logs.
6 years ago
#9
@
6 years ago
i'm still seeing the params formatted wrong.
https://developer.wordpress.org/reference/hooks/the_posts/
reopen?
#10
@
6 years ago
Thanks for pointing this out, @pcarvalho. I've opened a meta ticket to get this fixed in the parser: #META3171.
#11
@
6 years ago
- Keywords needs-patch added; has-patch removed
- Milestone set to 4.9
- Resolution worksforme deleted
- Status changed from closed to reopened
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.
I think we should rather fix the parser instead of making the docs "incorrect". What do you think, @DrewAPicture?