[wp-trac] [WordPress Trac] #25475: Hook Docs: wp-includes/cron.php

[WordPress Trac]

#25475: Hook Docs: wp-includes/cron.php
--------------------------+------------------------------
 Reporter:  tmtoy         |       Owner:  DrewAPicture
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  Awaiting Review
Component:  Inline Docs   |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  needs-patch   |
--------------------------+------------------------------
Changes (by DrewAPicture):

 * keywords:  has-patch => needs-patch
 * milestone:  3.7 => Awaiting Review


Comment:

 Thanks for the patch. Some notes on [attachment:cron.diff]:
 Overall:
 * For filters, the suggested language for the short description is "Filter
 <this thing>", so for all of the filter docs in your patch, keep that in
 mind. Some examples: "Filter a single scheduled event", "Filter whether to
 SSL verify the cron request", etc.
 * For array hash notations, the opening line should use always use an
 `@param` tag. Parameters should use `@type` and be indented four spaces.
 See the [http://make.wordpress.org/core/handbook/inline-documentation-
 standards/php-documentation-standards/#1-1-parameters-that-are-arrays
 inline docs template] for the style we're using.
 * There should be a space between the array variable and the opening brace
 for hash notations. `@param array $variable{` becomes `@param array
 $variable {`

 `schedule_event` filter:
 * `$event` is an array cast to an object, so referring to it as an array
 in the hash notation is incorrect.
 * Another option would be to change the value of `$event` above the docs
 to just an array, and then cast the value of the filter as an object. The
 hash notation also needs a short description (indented four spaces
 followed by a blank line.)

 `https_local_ssl_verify` filter:
 * Try to avoid jargon, in this case, "SecureSocketsLayer".
 * There's no need to assign the boolean value to a variable first, just
 reference the value directly in the parameter doc.

 `cron_request` filter:
 * Break the array out of the filter line and assign it to a variable above
 the doc. This allows you to reference the variable containing the array in
 the doc.
 * Needs a short description for the hash notation (same as
 `schedule_event`).
 * Space between `array{`
 * Specify the default for boolean values at the end of the parameter
 descriptions

 `cron_schedules` filter:
 * The hash notation opening line should use `@param`
 * Fix hash notation spacing
 * Use variable-style names instead of array keys. `'hourly'` becomes
 `$hourly`, `'interval'` becomes `$interval`, etc.

 I'm happy to clarify anything that doesn't make sense. Since the hash
 notation style is very new, we're trying to be very particular about how
 everything comes together. Looking forward to your next patch!

--
Ticket URL: <http://core.trac.wordpress.org/ticket/25475#comment:3>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software