Make WordPress Core

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: sudar's profile sudar 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)

35974.patch (19.7 KB) - added by sudar 7 years ago.

Download all attachments as: .zip

Change History (15)

@sudar
7 years ago

#1 @sudar
7 years ago

  • Keywords has-patch added

#2 follow-up: @swissspidy
7 years ago

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

#3 in reply to: ↑ 2 @DrewAPicture
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 @sudar
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 @SergeyBiryukov
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

#6 @chriscct7
7 years ago

  • Version trunk deleted

#7 @swissspidy
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 @pcarvalho
6 years ago

i'm still seeing the params formatted wrong.

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

reopen?

#10 @johnbillion
6 years ago

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

#11 @johnbillion
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.

#12 @johnbillion
6 years ago

In 41686:

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

Props sudar for the original patch.

See #35974

#13 @johnbillion
6 years ago

In 41688:

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

See #35974, #41017

#14 @johnbillion
6 years ago

  • Resolution set to fixed
  • Status changed from reopened to closed
Note: See TracTickets for help on using tickets.