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

[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.
 *

[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.

[DrewAPicture]

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().

[mnelson4]

@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?

[coffee2code]

In 6383:

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

Fixes #3165.

[coffee2code]

Tag with description

[coffee2code]

Tag without description

[coffee2code]

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

• Multiple tags: ​https://developer.wordpress.org/reference/functions/wp_enqueue_script/
• Tag with description: ​https://developer.wordpress.org/reference/functions/wp_remote_request/
• Tag with no description: ​https://developer.wordpress.org/reference/functions/register_widget/

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