WordPress.org

Making WordPress.org

Opened 5 years ago

Closed 5 years ago

#562 closed enhancement (fixed)

Convert doc block @link references to actual links

Reported by: coffee2code Owned by: coffee2code
Milestone: Priority: normal
Component: Developer Hub Keywords:
Cc:

Description

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:
    e.g. {@link sanitize_post()}
    see: get_post()
  1. Link to a method
    e.g.{@link WP_Roles::remove_cap()}
    see: WP_Role::remove_cap()
  1. Link to a class property
    e.g. {@link WP_Rewrite::$extra_permastructs}
    see: WP_Rewrite::add_permastruct()
    Note: since devhub doesn't currently document class properties, this shouldn't link to anything.
  1. Link to an external site (with link text)
    e.g. {@link https://api.wordpress.org/secret-key/1.1/salt/ secret key created}
    see: wp_salt()
  1. Link to external site (without link text)
    e.g. {@link http://en.wikipedia.org/wiki/ISO_8601}
    see: iso860_to_datetime()
    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.

Change History (1)

#1 @coffee2code
5 years ago

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

In 751:

Code Reference: convert doc block @link references to actual links. Fixes #562

Note: See TracTickets for help on using tickets.