WordPress.org

Making WordPress.org

Opened 3 months ago

Last modified 2 months ago

#3165 new enhancement

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

Reported by: DrewAPicture Owned by:
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.
 *

Change History (5)

#1 @DrewAPicture
3 months ago

  • Description modified (diff)

#2 @DrewAPicture
3 months ago

  • Description modified (diff)

#3 follow-up: @mnelson4
3 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 3 months ago by mnelson4 (previous) (diff)

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

Note: See TracTickets for help on using tickets.