[wp-trac] [WordPress Trac] #45445: Cron-related documentation incorrectly uses `@see` syntax in a number of places

[WordPress Trac]

#45445: Cron-related documentation incorrectly uses `@see` syntax in a number of
places
--------------------------+-----------------------------
 Reporter:  coffee2code   |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  low           |  Milestone:  Awaiting Review
Component:  Cron API      |    Version:  trunk
 Severity:  minor         |   Keywords:  has-patch
  Focuses:  docs          |
--------------------------+-----------------------------
 Cron-related hooks committed and slated for 5.1 were introduced with
 docblocks that incorrectly use the `@see` syntax to reference hooks and
 functions. The incorrect uses were of the format `{@see
 pre_unschedule_event}`. This is ambiguous as to what is being referenced.
 Currently, the Code Reference would only try to link each of these to a
 function, assuming such a function exists.

 In the case of hooks (which were the most common occurrences of this
 problem), the syntax should be `{@see 'pre_unschedule_event'}` (note the
 single quotes).

 In the case of functions, something like `{@see wp_get_schedules}` should
 be `{@see wp_get_schedules()}`. However, it is not necessary to use the
 `@see` syntax when referencing functions, classes, or methods since they
 can be inferred (and are inferred and auto-linked by the Code Reference).

 ''The documentation standards [https://make.wordpress.org/core/handbook
 /best-practices/inline-documentation-standards/php/#other-descriptions
 mention] the use of `@see` for referencing hooks, but could stand to be
 more explicit about not needing to be used for functions, classes, or
 class methods.''

 These were introduced mostly from [43540] (but also [43050] and [43608]).

 Related: #32656.

 The attached patch fixes the hook references and removes explicit
 referencing of a few functions (all of which were added in the
 aforementioned commits).

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/45445>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform