[wp-meta] [Making WordPress.org] #3165: Expose top-level @see tag contents in code reference pages

[Making WordPress.org]

#3165: Expose top-level @see tag contents in code reference pages
---------------------------+------------------
 Reporter:  DrewAPicture   |       Owner:
     Type:  enhancement    |      Status:  new
 Priority:  normal         |   Milestone:
Component:  Developer Hub  |  Resolution:
 Keywords:  needs-patch    |
---------------------------+------------------
Description changed by DrewAPicture:

Old description:

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

New description:

 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()`:
 {{{
 #!php
  *
  * @see WP_Http::request() For additional information on default
 arguments.
  *
 }}}

--

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/3165#comment:2>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org