[wp-meta] [Making WordPress.org] #562: Convert doc block @link references to actual links

[Making WordPress.org]

#562: Convert doc block @link references to actual links
------------------------+-------------------------------------
Reporter:  coffee2code  |      Owner:
    Type:  enhancement  |     Status:  new
Priority:  normal       |  Component:  developer.wordpress.org
Keywords:               |
------------------------+-------------------------------------
 Doc blocks contain an @link syntax for linking to other resources from
 within the description of a function/method/etc (or for its parameters).
 These should be converted on display to clickable links. ''(Arguably, they
 should be converted on initial parsing. This won't conflict if that ever
 becomes the case.)''

 I've identified five variations of the use of @link:

 1. Link to a function: [[br]] e.g. `{@link sanitize_post()}` [[br]] see:
 [http://developer.wordpress.org/reference/functions/get_post/ get_post()]

 2. Link to a method [[br]] e.g.`{@link WP_Roles::remove_cap()}` [[br]]
 see: [http://developer.wordpress.org/reference/classes/wp_role/remove_cap/
 WP_Role::remove_cap()]

 3. Link to a class property [[br]] e.g. `{@link
 WP_Rewrite::$extra_permastructs}` [[br]] see:
 [http://developer.wordpress.org/reference/classes/wp_rewrite/add_permastruct/
 WP_Rewrite::add_permastruct()] [[br]] ''Note: since devhub doesn't
 currently document class properties, this shouldn't link to anything.''

 4. Link to an external site (with link text) [[br]] e.g. `{@link
 https://api.wordpress.org/secret-key/1.1/salt/ secret key created}` [[br]]
 see: [http://developer.wordpress.org/reference/functions/wp_salt/
 wp_salt()]

 5. Link to external site (without link text) [[br]] e.g. `{@link
 http://en.wikipedia.org/wiki/ISO_8601}` [[br]] see:
 [http://developer.wordpress.org/reference/functions/iso8601_to_datetime/
 iso860_to_datetime()] [[br]] ''These should probably all be changed in
 core to have link text. There are only 3 uses of this syntax.''

 In all cases, the "@link" and wrapping braces should be removed. In all
 but the one noted case (item 3), an appropriate link should replace the
 syntax. For item 3, the content of the @link should be replaced back in.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/562>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org