WordPress.org

Making WordPress.org

Opened 10 months ago

Closed 6 months ago

Last modified 6 months ago

#3165 closed enhancement (fixed)

Expose top-level @see tag contents in code reference pages

Reported by: DrewAPicture Owned by: coffee2code
Milestone: Priority: normal
Component: Developer Hub Keywords: needs-patch
Cc:

Description (last modified by DrewAPicture)

Recently received a contributor note from @mnelson4 on the reference for wp_remote_request() asking about which arguments are accepted, and I realized that we explicitly point to WP_Http::request() for additional information on default arguments, except that information isn't exposed anywhere in the wporg-developer theme.

I can’t find anywhere on developer.wordpress.org that explains what array keys and values $args should have in either wp_remote_request, wp_remote_post, wp_remote_get or wp_remote_head.

The codex went over some of the arguments here: https://codex.wordpress.org/HTTP_API (although not all, it missed body, for example), and it also has an example that uses a bunch of them here: https://codex.wordpress.org/Function_Reference/wp_remote_post, but that’s just an example not documentation.

I'm thinking maybe we should just expose the contents of the top-level @see tags at the end of the description, rather than as part of the explanation (since it's parsed). Either way, this is one very good example of where useful information in the docblock isn't getting translated into the Code Reference for the wider audience.

From the DocBlock for wp_remote_request():

 *
 * @see WP_Http::request() For additional information on default arguments.
 *

Attachments (2)

meta-3165_1.png (262.7 KB) - added by coffee2code 6 months ago.
Tag with description
meta-3165_2.png (155.7 KB) - added by coffee2code 6 months ago.
Tag without description

Download all attachments as: .zip

Change History (9)

#1 @DrewAPicture
10 months ago

  • Description modified (diff)

#2 @DrewAPicture
10 months ago

  • Description modified (diff)

#3 follow-up: @mnelson4
10 months ago

I'm thinking maybe we should just expose the contents of the top-level @see tags at the end of the description, rather than as part of the explanation (since it's parsed).

Yeah I think that would be a great start; it would be ideal if whatever was after @see was actually a link to the relevant docs page.

e.g., a PHPDoc of @see WP_Http::request() For additional information on default arguments. would become the HTML See <a href="https://developer.wordpress.org/reference/classes/wp_http/request/">WP_HTTP::request()</a> For additional information on default arguments. on developer.wordpress.org.

But I suspect making that a link might be tricky, so just starting with an easier change would be good.

Last edited 10 months ago by mnelson4 (previous) (diff)

#4 in reply to: ↑ 3 @DrewAPicture
9 months ago

Replying to mnelson4:

I'm thinking maybe we should just expose the contents of the top-level @see tags at the end of the description, rather than as part of the explanation (since it's parsed).

Yeah I think that would be a great start; it would be ideal if whatever was after @see was actually a link to the relevant docs page.

e.g., a PHPDoc of @see WP_Http::request() For additional information on default arguments. would become the HTML See <a href="https://developer.wordpress.org/reference/classes/wp_http/request/">WP_HTTP::request()</a> For additional information on default arguments. on developer.wordpress.org.

But I suspect making that a link might be tricky, so just starting with an easier change would be good.

@see is actually for referencing function, class, method, or hooks. If you're wanting to reference an external link like that, the best option is to use an inline @link tag, which DevHub is already setup to handle.

For an example of how that works in practice, check out the reference changleog and DocBlock for register_meta().

#5 @mnelson4
9 months ago

@see is actually for referencing function, class, method, or hooks. If you're wanting to reference an external link like that, the best option is to use an inline @link tag, which DevHub is already setup to handle.

Oh ok, although that's not exactly what I was thinking. I was suggesting that the contents of the PHP doc could remain like @see WP_Http::request(), but when your script is parsing that and generating the HTML from it to display on developer.wordpress.org, it would be great if instead of just showing that exact string, it would basically go "Hey, this PHP doc comment is referencing another function. I know the link to that function/class is on developer.wordpress.org! So I'll provide a link to it, instead of just getting users to search for it themselves." ie, somehow translate the function/class/method/hook into the URL where that thing is documented on developer.wordpress.org, and then generate a link to it.

Does that make sense? I think it would be good but it's probably dreaming. And sorry, where is the code that does this parsing?

#6 @coffee2code
6 months ago

  • Owner set to coffee2code
  • Resolution set to fixed
  • Status changed from new to closed

In 6383:

developer.wordpress.org: Append heretofore unshown @see tags from docblocks to list at end of description.

Fixes #3165.

@coffee2code
6 months ago

Tag with description

@coffee2code
6 months ago

Tag without description

#7 @coffee2code
6 months ago

Some examples of function-level @see tags now being shown (also works for classes and methods):

Attached images meta-3165_1.png and meta-3165_2.png showing examples of how the tags are now shown.

Note: See TracTickets for help on using tickets.