WordPress.org

Make WordPress Core

Changeset 46232


Ignore:
Timestamp:
09/21/2019 05:40:58 PM (4 weeks ago)
Author:
johnbillion
Message:

Docs: Docblock corrections and improvements, mostly related to various pre_* filters.

See #47110

Location:
trunk/src
Files:
18 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/file.php

    r46230 r46232  
    853853     * @since 4.9.0
    854854     *
    855      * @param string $move_new_file If null (default) move the file after the upload.
    856      * @param string $file          An array of data for a single file.
    857      * @param string $new_file      Filename of the newly-uploaded file.
    858      * @param string $type          File type.
     855     * @param mixed    $move_new_file If null (default) move the file after the upload.
     856     * @param string[] $file          An array of data for a single file.
     857     * @param string   $new_file      Filename of the newly-uploaded file.
     858     * @param string   $type          File type.
    859859     */
    860860    $move_new_file = apply_filters( 'pre_move_uploaded_file', null, $file, $new_file, $type );
  • trunk/src/wp-admin/includes/theme.php

    r45932 r46232  
    687687     * @since 3.8.0
    688688     *
    689      * @param array $prepared_themes Array of themes.
     689     * @param array $prepared_themes Array of theme data.
    690690     */
    691691    $prepared_themes = apply_filters( 'wp_prepare_themes_for_js', $prepared_themes );
  • trunk/src/wp-includes/blocks.php

    r46111 r46232  
    226226     * @since 5.1.0
    227227     *
    228      * @param string $pre_render The pre-rendered content. Default null.
    229      * @param array  $block      The block being rendered.
     228     * @param string|null $pre_render The pre-rendered content. Default null.
     229     * @param array       $block      The block being rendered.
    230230     */
    231231    $pre_render = apply_filters( 'pre_render_block', null, $block );
  • trunk/src/wp-includes/class-http.php

    r45667 r46232  
    252252         *
    253253         * @param false|array|WP_Error $preempt Whether to preempt an HTTP request's return value. Default false.
    254          * @param array               $parsed_args        HTTP request arguments.
    255          * @param string              $url      The request URL.
     254         * @param array                $parsed_args        HTTP request arguments.
     255         * @param string               $url      The request URL.
    256256         */
    257257        $pre = apply_filters( 'pre_http_request', false, $parsed_args, $url );
  • trunk/src/wp-includes/class-wp-http-proxy.php

    r42343 r46232  
    153153
    154154    /**
    155      * Whether URL should be sent through the proxy server.
    156      *
    157      * We want to keep localhost and the site URL from being sent through the proxy server, because
     155     * Determines whether the request should be sent through a proxy.
     156     *
     157     * We want to keep localhost and the site URL from being sent through the proxy, because
    158158     * some proxies can not handle this. We also have the constant available for defining other
    159159     * hosts that won't be sent through the proxy.
     
    182182
    183183        /**
    184          * Filters whether to preempt sending the request through the proxy server.
     184         * Filters whether to preempt sending the request through the proxy.
    185185         *
    186186         * Returning false will bypass the proxy; returning true will send
     
    189189         * @since 3.5.0
    190190         *
    191          * @param null  $override Whether to override the request result. Default null.
    192          * @param string $uri      URL to check.
    193          * @param array  $check    Associative array result of parsing the URI.
    194          * @param array  $home     Associative array result of parsing the site URL.
     191         * @param bool|null $override Whether to override the request result. Default null.
     192         * @param string    $uri      URL to check.
     193         * @param array     $check    Associative array result of parsing the request URI.
     194         * @param array     $home     Associative array result of parsing the site URL.
    195195         */
    196196        $result = apply_filters( 'pre_http_send_through_proxy', null, $uri, $check, $home );
  • trunk/src/wp-includes/class-wp-xmlrpc-server.php

    r46150 r46232  
    287287             * @since 3.5.0
    288288             *
    289              * @param string  $error The XML-RPC error message.
    290              * @param WP_User $user  WP_User object.
     289             * @param string   $error The XML-RPC error message.
     290             * @param WP_Error $user  WP_Error object.
    291291             */
    292292            $this->error = apply_filters( 'xmlrpc_login_error', $this->error, $user );
  • trunk/src/wp-includes/comment.php

    r46227 r46232  
    821821     *              allow skipping further processing.
    822822     *
    823      * @param bool|string|WP_Error $approved    The approval status. Accepts 1, 0, 'spam' or WP_Error.
    824      * @param array                $commentdata Comment data.
     823     * @param int|string|WP_Error $approved    The approval status. Accepts 1, 0, 'spam' or WP_Error.
     824     * @param array               $commentdata Comment data.
    825825     */
    826826    $approved = apply_filters( 'pre_comment_approved', $approved, $commentdata );
     
    24892489 *
    24902490 * @param int $post_id Post ID
    2491  * @return bool True on success, false on '0' $post_id or if post with ID does not exist.
     2491 * @return bool True on success, false if the post does not exist.
    24922492 */
    24932493function wp_update_comment_count_now( $post_id ) {
     
    25132513     * @since 4.5.0
    25142514     *
    2515      * @param int $new     The new comment count. Default null.
    2516      * @param int $old     The old comment count.
    2517      * @param int $post_id Post ID.
     2515     * @param int|null $new     The new comment count. Default null.
     2516     * @param int      $old     The old comment count.
     2517     * @param int      $post_id Post ID.
    25182518     */
    25192519    $new = apply_filters( 'pre_wp_update_comment_count_now', null, $old, $post_id );
  • trunk/src/wp-includes/cron.php

    r45674 r46232  
    393393 *
    394394 * @param string $hook Action hook, the execution of which will be unscheduled.
    395  * @param array $args Optional. Arguments that were to be passed to the hook's callback function.
    396  * @return bool|int On success an integer indicating number of events unscheduled (0 indicates no
    397  *                  events were registered with the hook and arguments combination), false if
    398  *                  unscheduling one or more events fail.
     395 * @param array  $args Optional. Arguments that were to be passed to the hook's callback function.
     396 * @return false|int On success an integer indicating number of events unscheduled (0 indicates no
     397 *                   events were registered with the hook and arguments combination), false if
     398 *                   unscheduling one or more events fail.
    399399 */
    400400function wp_clear_scheduled_hook( $hook, $args = array() ) {
     
    418418     * @since 5.1.0
    419419     *
    420      * @param null|array $pre  Value to return instead. Default null to continue unscheduling the event.
    421      * @param string     $hook Action hook, the execution of which will be unscheduled.
    422      * @param array      $args Arguments to pass to the hook's callback function.
     420     * @param null|int|false $pre  Value to return instead. Default null to continue unscheduling the event.
     421     * @param string         $hook Action hook, the execution of which will be unscheduled.
     422     * @param array          $args Arguments to pass to the hook's callback function.
    423423     */
    424424    $pre = apply_filters( 'pre_clear_scheduled_hook', null, $hook, $args );
     
    462462 *
    463463 * @param string $hook Action hook, the execution of which will be unscheduled.
    464  * @return bool|int On success an integer indicating number of events unscheduled (0 indicates no
    465  *                  events were registered on the hook), false if unscheduling fails.
     464 * @return false|int On success an integer indicating number of events unscheduled (0 indicates no
     465 *                   events were registered on the hook), false if unscheduling fails.
    466466 */
    467467function wp_unschedule_hook( $hook ) {
     
    478478     * @since 5.1.0
    479479     *
    480      * @param null|array $pre  Value to return instead. Default null to continue unscheduling the hook.
    481      * @param string     $hook Action hook, the execution of which will be unscheduled.
     480     * @param null|int|false $pre  Value to return instead. Default null to continue unscheduling the hook.
     481     * @param string         $hook Action hook, the execution of which will be unscheduled.
    482482     */
    483483    $pre = apply_filters( 'pre_unschedule_hook', null, $hook );
     
    529529 *                            event, so they should be the same as those used when originally scheduling the event.
    530530 * @param int|null $timestamp Optional. Unix timestamp (UTC) of the event. If not specified, the next scheduled event is returned.
    531  * @return bool|object The event object. False if the event does not exist.
     531 * @return false|object The event object. False if the event does not exist.
    532532 */
    533533function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
     
    543543     * @since 5.1.0
    544544     *
    545      * @param null|bool $pre       Value to return instead. Default null to continue retrieving the event.
    546      * @param string    $hook      Action hook of the event.
    547      * @param array     $args      Array containing each separate argument to pass to the hook's callback function.
    548      *                             Although not passed to a callback, these arguments are used to uniquely identify the
    549      *                             event.
     545     * @param null|false|object $pre  Value to return instead. Default null to continue retrieving the event.
     546     * @param string            $hook Action hook of the event.
     547     * @param array             $args Array containing each separate argument to pass to the hook's callback function.
     548     *                                Although not passed to a callback, these arguments are used to uniquely identify
     549     *                                the event.
    550550     * @param int|null  $timestamp Unix timestamp (UTC) of the event. Null to retrieve next scheduled event.
    551551     */
  • trunk/src/wp-includes/formatting.php

    r46214 r46232  
    38373837     * @since 3.3.0
    38383838     *
    3839      * @param null  $converted_text The text to be converted. Default null.
    3840      * @param string $text           The text prior to entity conversion.
     3839     * @param string|null $converted_text The text to be converted. Default null.
     3840     * @param string      $text           The text prior to entity conversion.
    38413841     */
    38423842    $filtered = apply_filters( 'pre_ent2ncr', null, $text );
  • trunk/src/wp-includes/l10n.php

    r45738 r46232  
    10541054     * @since 5.0.2
    10551055     *
    1056      * @param string|false $translations JSON-encoded translation data. Default null.
    1057      * @param string|false $file         Path to the translation file to load. False if there isn't one.
    1058      * @param string       $handle       Name of the script to register a translation domain to.
    1059      * @param string       $domain       The text domain.
     1056     * @param string|false|null $translations JSON-encoded translation data. Default null.
     1057     * @param string|false      $file         Path to the translation file to load. False if there isn't one.
     1058     * @param string            $handle       Name of the script to register a translation domain to.
     1059     * @param string            $domain       The text domain.
    10601060     */
    10611061    $translations = apply_filters( 'pre_load_script_translations', null, $file, $handle, $domain );
  • trunk/src/wp-includes/link-template.php

    r45932 r46232  
    39983998 * @since 4.2.0
    39993999 *
    4000  * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
    4001  *                            user email, WP_User object, WP_Post object, or WP_Comment object.
     4000 * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
     4001 *                           user email, WP_User object, WP_Post object, or WP_Comment object.
    40024002 * @param array $args {
    40034003 *     Optional. Arguments to return instead of the default arguments.
     
    40214021 *     @type string $extra_attr     HTML attributes to insert in the IMG element. Is not sanitized. Default empty.
    40224022 * }
    4023  * @return array $processed_args {
     4023 * @return array {
    40244024 *     Along with the arguments passed in `$args`, this will contain a couple of extra arguments.
    40254025 *
     
    41024102     * @since 4.2.0
    41034103     *
    4104      * @param array  $args        Arguments passed to get_avatar_data(), after processing.
    4105      * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
    4106      *                            user email, WP_User object, WP_Post object, or WP_Comment object.
     4104     * @param array $args        Arguments passed to get_avatar_data(), after processing.
     4105     * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
     4106     *                           user email, WP_User object, WP_Post object, or WP_Comment object.
    41074107     */
    41084108    $args = apply_filters( 'pre_get_avatar_data', $args, $id_or_email );
     
    41944194     *
    41954195     * @param string $url         The URL of the avatar.
    4196      * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
     4196     * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
    41974197     *                            user email, WP_User object, WP_Post object, or WP_Comment object.
    41984198     * @param array  $args        Arguments passed to get_avatar_data(), after processing.
     
    42054205     * @since 4.2.0
    42064206     *
    4207      * @param array  $args        Arguments passed to get_avatar_data(), after processing.
    4208      * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
    4209      *                            user email, WP_User object, WP_Post object, or WP_Comment object.
     4207     * @param array $args        Arguments passed to get_avatar_data(), after processing.
     4208     * @param mixed $id_or_email The Gravatar to retrieve. Accepts a user ID, Gravatar MD5 hash,
     4209     *                           user email, WP_User object, WP_Post object, or WP_Comment object.
    42104210     */
    42114211    return apply_filters( 'get_avatar_data', $args, $id_or_email );
  • trunk/src/wp-includes/ms-functions.php

    r45932 r46232  
    24272427
    24282428/**
    2429  * Returns the space used by the current blog.
     2429 * Returns the space used by the current site.
    24302430 *
    24312431 * @since 3.5.0
    24322432 *
    2433  * @return int Used space in megabytes
     2433 * @return int Used space in megabytes.
    24342434 */
    24352435function get_space_used() {
    24362436    /**
    2437      * Filters the amount of storage space used by the current site.
     2437     * Filters the amount of storage space used by the current site, in megabytes.
    24382438     *
    24392439     * @since 3.5.0
    24402440     *
    2441      * @param int|bool $space_used The amount of used space, in megabytes. Default false.
     2441     * @param int|false $space_used The amount of used space, in megabytes. Default false.
    24422442     */
    24432443    $space_used = apply_filters( 'pre_get_space_used', false );
  • trunk/src/wp-includes/ms-load.php

    r45932 r46232  
    204204     * @since 3.9.0
    205205     *
    206      * @param null|bool|WP_Site $site     Site value to return by path.
    207      * @param string            $domain   The requested domain.
    208      * @param string            $path     The requested path, in full.
    209      * @param int|null          $segments The suggested number of paths to consult.
    210      *                                    Default null, meaning the entire path was to be consulted.
    211      * @param array             $paths    The paths to search for, based on $path and $segments.
     206     * @param null|false|WP_Site $site     Site value to return by path.
     207     * @param string             $domain   The requested domain.
     208     * @param string             $path     The requested path, in full.
     209     * @param int|null           $segments The suggested number of paths to consult.
     210     *                                     Default null, meaning the entire path was to be consulted.
     211     * @param array              $paths    The paths to search for, based on $path and $segments.
    212212     */
    213213    $pre = apply_filters( 'pre_get_site_by_path', null, $domain, $path, $segments, $paths );
  • trunk/src/wp-includes/pluggable.php

    r46116 r46232  
    26092609         * @since 4.2.0
    26102610         *
    2611          * @param string $avatar      HTML for the user's avatar. Default null.
    2612          * @param mixed  $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
    2613          *                            user email, WP_User object, WP_Post object, or WP_Comment object.
    2614          * @param array  $args        Arguments passed to get_avatar_url(), after processing.
     2611         * @param string|null $avatar      HTML for the user's avatar. Default null.
     2612         * @param mixed       $id_or_email The Gravatar to retrieve. Accepts a user_id, gravatar md5 hash,
     2613         *                                 user email, WP_User object, WP_Post object, or WP_Comment object.
     2614         * @param array       $args        Arguments passed to get_avatar_url(), after processing.
    26152615         */
    26162616        $avatar = apply_filters( 'pre_get_avatar', null, $id_or_email, $args );
  • trunk/src/wp-includes/post.php

    r46196 r46232  
    29362936     * @since 4.4.0
    29372937     *
    2938      * @param bool    $delete       Whether to go forward with deletion.
    2939      * @param WP_Post $post         Post object.
    2940      * @param bool    $force_delete Whether to bypass the trash.
     2938     * @param bool|null $delete       Whether to go forward with deletion.
     2939     * @param WP_Post   $post         Post object.
     2940     * @param bool      $force_delete Whether to bypass the trash.
    29412941     */
    29422942    $check = apply_filters( 'pre_delete_post', null, $post, $force_delete );
     
    31053105     * @since 4.9.0
    31063106     *
    3107      * @param bool    $trash Whether to go forward with trashing.
    3108      * @param WP_Post $post  Post object.
     3107     * @param bool|null $trash Whether to go forward with trashing.
     3108     * @param WP_Post   $post  Post object.
    31093109     */
    31103110    $check = apply_filters( 'pre_trash_post', null, $post );
     
    31743174     * @since 4.9.0
    31753175     *
    3176      * @param bool    $untrash Whether to go forward with untrashing.
    3177      * @param WP_Post $post    Post object.
     3176     * @param bool|null $untrash Whether to go forward with untrashing.
     3177     * @param WP_Post   $post    Post object.
    31783178     */
    31793179    $check = apply_filters( 'pre_untrash_post', null, $post );
     
    42854285     * @since 5.1.0
    42864286     *
    4287      * @param string $override_slug Short-circuit return value.
    4288      * @param string $slug          The desired slug (post_name).
    4289      * @param int    $post_ID       Post ID.
    4290      * @param string $post_status   The post status.
    4291      * @param string $post_type     Post type.
    4292      * @param int    $post_parent   Post parent ID.
     4287     * @param string|null $override_slug Short-circuit return value.
     4288     * @param string      $slug          The desired slug (post_name).
     4289     * @param int         $post_ID       Post ID.
     4290     * @param string      $post_status   The post status.
     4291     * @param string      $post_type     Post type.
     4292     * @param int         $post_parent   Post parent ID.
    42934293     */
    42944294    $override_slug = apply_filters( 'pre_wp_unique_post_slug', null, $slug, $post_ID, $post_status, $post_type, $post_parent );
     
    63526352
    63536353/**
    6354  * Retrieve the date that the last post was published.
     6354 * Retrieves the most recent time that a post on the site was published.
    63556355 *
    63566356 * The server timezone is the default and is the difference between GMT and
     
    63636363 * @param string $timezone  Optional. The timezone for the timestamp. Accepts 'server', 'blog', or 'gmt'.
    63646364 *                          'server' uses the server's internal timezone.
    6365  *                          'blog' uses the `post_modified` field, which proxies to the timezone set for the site.
    6366  *                          'gmt' uses the `post_modified_gmt` field.
     6365 *                          'blog' uses the `post_date` field, which proxies to the timezone set for the site.
     6366 *                          'gmt' uses the `post_date_gmt` field.
    63676367 *                          Default 'server'.
    63686368 * @param string $post_type Optional. The post type to check. Default 'any'.
     
    63716371function get_lastpostdate( $timezone = 'server', $post_type = 'any' ) {
    63726372    /**
    6373      * Filters the date the last post was published.
     6373     * Filters the most recent time that a post on the site was published.
    63746374     *
    63756375     * @since 2.3.0
     
    63836383
    63846384/**
    6385  * Get the timestamp of the last time any post was modified.
     6385 * Get the most recent time that a post on the site was modified.
    63866386 *
    63876387 * The server timezone is the default and is the difference between GMT and
     
    63966396 *                          Default 'server'.
    63976397 * @param string $post_type Optional. The post type to check. Default 'any'.
    6398  * @return string The timestamp.
     6398 * @return string The timestamp in 'Y-m-d H:i:s' format.
    63996399 */
    64006400function get_lastpostmodified( $timezone = 'server', $post_type = 'any' ) {
     
    64046404     * @since 4.4.0
    64056405     *
    6406      * @param string $lastpostmodified Date the last post was modified.
    6407      *                                 Returning anything other than false will short-circuit the function.
    6408      * @param string $timezone         Location to use for getting the post modified date.
    6409      *                                 See get_lastpostdate() for accepted `$timezone` values.
    6410      * @param string $post_type        The post type to check.
     6406     * @param string|false $lastpostmodified The most recent time that a post was modified, in 'Y-m-d H:i:s' format, or
     6407     *                                       false. Returning anything other than false will short-circuit the function.
     6408     * @param string       $timezone         Location to use for getting the post modified date.
     6409     *                                       See get_lastpostdate() for accepted `$timezone` values.
     6410     * @param string       $post_type        The post type to check.
    64116411     */
    64126412    $lastpostmodified = apply_filters( 'pre_get_lastpostmodified', false, $timezone, $post_type );
     
    64236423
    64246424    /**
    6425      * Filters the date the last post was modified.
     6425     * Filters the most recent time that a post was modified.
    64266426     *
    64276427     * @since 2.3.0
    64286428     *
    6429      * @param string $lastpostmodified Date the last post was modified.
     6429     * @param string $lastpostmodified The most recent time that a post was modified, in 'Y-m-d H:i:s' format.
    64306430     * @param string $timezone         Location to use for getting the post modified date.
    64316431     *                                 See get_lastpostdate() for accepted `$timezone` values.
     
    64356435
    64366436/**
    6437  * Get the timestamp of the last time any post was modified or published.
     6437 * Gets the timestamp of the last time any post was modified or published.
    64386438 *
    64396439 * @since 3.1.0
     
    64476447 * @param string $field     Post field to check. Accepts 'date' or 'modified'.
    64486448 * @param string $post_type Optional. The post type to check. Default 'any'.
    6449  * @return string|false The timestamp.
     6449 * @return string|false The timestamp in 'Y-m-d H:i:s' format, or false on error.
    64506450 */
    64516451function _get_last_post_time( $timezone, $field, $post_type = 'any' ) {
  • trunk/src/wp-includes/shortcodes.php

    r45932 r46232  
    306306     * Filters whether to call a shortcode callback.
    307307     *
    308      * Passing a truthy value to the filter will effectively short-circuit the
     308     * Returning a non-false value from filter will short-circuit the
    309309     * shortcode generation process, returning that value instead.
    310310     *
    311311     * @since 4.7.0
    312312     *
    313      * @param bool|string $return      Short-circuit return value. Either false or the value to replace the shortcode with.
     313     * @param false|string $return      Short-circuit return value. Either false or the value to replace the shortcode with.
    314314     * @param string       $tag         Shortcode name.
    315315     * @param array|string $attr        Shortcode attributes array or empty string.
  • trunk/src/wp-includes/taxonomy.php

    r46196 r46232  
    13591359 *
    13601360 * @param int|string $term     The term to check. Accepts term ID, slug, or name.
    1361  * @param string     $taxonomy The taxonomy name to use
     1361 * @param string     $taxonomy Optional. The taxonomy name to use.
    13621362 * @param int        $parent   Optional. ID of parent term under which to confine the exists search.
    13631363 * @return mixed Returns null if the term does not exist. Returns the term ID
     
    20982098 * @since 2.3.0
    20992099 *
    2100  * @param string       $term     The term to add or update.
     2100 * @param string       $term     The term name to add or update.
    21012101 * @param string       $taxonomy The taxonomy to which to add the term.
    21022102 * @param array|string $args {
     
    21182118        return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy.' ) );
    21192119    }
     2120
    21202121    /**
    21212122     * Filters a term before it is sanitized and inserted into the database.
     
    21232124     * @since 3.0.0
    21242125     *
    2125      * @param string $term     The term to add or update.
    2126      * @param string $taxonomy Taxonomy slug.
     2126     * @param string|WP_Error $term     The term name to add or update, or a WP_Error object if there's an error.
     2127     * @param string          $taxonomy Taxonomy slug.
    21272128     */
    21282129    $term = apply_filters( 'pre_insert_term', $term, $taxonomy );
  • trunk/src/wp-includes/wp-db.php

    r46194 r46232  
    27042704         * @since 4.2.0
    27052705         *
    2706          * @param string $charset The character set to use. Default null.
    2707          * @param string $table   The name of the table being checked.
     2706         * @param string|null $charset The character set to use. Default null.
     2707         * @param string      $table   The name of the table being checked.
    27082708         */
    27092709        $charset = apply_filters( 'pre_get_table_charset', null, $table );
     
    28082808         * @since 4.2.0
    28092809         *
    2810          * @param string $charset The character set to use. Default null.
    2811          * @param string $table   The name of the table being checked.
    2812          * @param string $column  The name of the column being checked.
     2810         * @param string|null $charset The character set to use. Default null.
     2811         * @param string      $table   The name of the table being checked.
     2812         * @param string      $column  The name of the column being checked.
    28132813         */
    28142814        $charset = apply_filters( 'pre_get_col_charset', null, $table, $column );
Note: See TracChangeset for help on using the changeset viewer.