WordPress.org
Get WordPress

Make WordPress Core

Changeset 55694


Ignore:
Timestamp:
04/27/2023 11:13:36 PM (3 years ago)
Author:
johnbillion
Message:

Docs: All sorts of improvements and corrections to function and hook docs.

See #57840

Location:
trunk/src
Files:
12 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/ms.php

    r55415 r55694  
    131131
    132132/**
    133  * Deletes a user from the network and remove from all sites.
     133 * Deletes a user and all of their posts from the network.
     134 *
     135 * This function:
     136 *
     137 * - Deletes all posts (of all post types) authored by the user on all sites on the network
     138 * - Deletes all links owned by the user on all sites on the network
     139 * - Removes the user from all sites on the network
     140 * - Deletes the user from the database
    134141 *
    135142 * @since 3.0.0
    136  *
    137  * @todo Merge with wp_delete_user()?
    138143 *
    139144 * @global wpdb $wpdb WordPress database abstraction object.

  • trunk/src/wp-admin/includes/user.php

    r55683 r55694  
    325325
    326326/**
    327  * Remove user and optionally reassign posts and links to another user.
    328  *
    329  * If the $reassign parameter is not assigned to a User ID, then all posts will
    330  * be deleted of that user. The action {@see 'delete_user'} that is passed the User ID
     327 * Delete user and optionally reassign posts and links to another user.
     328 *
     329 * Note that on a Multisite installation the user only gets removed from the site
     330 * and does not get deleted from the database.
     331 *
     332 * If the `$reassign` parameter is not assigned to a user ID, then all posts will
     333 * be deleted of that user. The action {@see 'delete_user'} that is passed the user ID
    331334 * being deleted will be run after the posts are either reassigned or deleted.
    332  * The user meta will also be deleted that are for that User ID.
     335 * The user meta will also be deleted that are for that user ID.
    333336 *
    334337 * @since 2.0.0
    … …  
    336339 * @global wpdb $wpdb WordPress database abstraction object.
    337340 *
    338  * @param int $id User ID.
     341 * @param int $id       User ID.
    339342 * @param int $reassign Optional. Reassign posts and links to new User ID.
    340343 * @return bool True when finished.
    … …  
    362365
    363366    /**
    364      * Fires immediately before a user is deleted from the database.
     367     * Fires immediately before a user is deleted from the site.
     368     *
     369     * Note that on a Multisite installation the user only gets removed from the site
     370     * and does not get deleted from the database.
    365371     *
    366372     * @since 2.0.0
    … …  
    441447
    442448    /**
    443      * Fires immediately after a user is deleted from the database.
     449     * Fires immediately after a user is deleted from the site.
     450     *
     451     * Note that on a Multisite installation the user may not have been deleted from
     452     * the database depending on whether `wp_delete_user()` or `wpmu_delete_user()`
     453     * was called.
    444454     *
    445455     * @since 2.9.0

  • trunk/src/wp-includes/block-template-utils.php

    r55693 r55694  
    300300 *     @type array  $slug__in     List of slugs to include.
    301301 *     @type array  $slug__not_in List of slugs to skip.
    302  *     @type string $area         A 'wp_template_part_area' taxonomy value to filter by (for wp_template_part template type only).
     302 *     @type string $area         A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
    303303 *     @type string $post_type    Post type to get the templates for.
    304304 * }
    … …  
    756756 *
    757757 * @param WP_Post $post Template post.
    758  * @return WP_Block_Template|WP_Error Template.
     758 * @return WP_Block_Template|WP_Error Template or error object.
    759759 */
    760760function _build_block_template_result_from_post( $post ) {
    … …  
    10561056 * @since 5.8.0
    10571057 *
    1058  * @param string $id            Template unique identifier (example: theme_slug//template_slug).
    1059  * @param string $template_type Optional. Template type: `'wp_template'` or '`wp_template_part'`.
    1060  *                              Default `'wp_template'`.
     1058 * @param string $id            Template unique identifier (example: 'theme_slug//template_slug').
     1059 * @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
     1060 *                              Default 'wp_template'.
    10611061 * @return WP_Block_Template|null Template.
    10621062 */
    … …  
    10711071     * @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
    10721072     *                                               or null to allow WP to run its normal queries.
    1073      * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
    1074      * @param string                 $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
     1073     * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
     1074     * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
    10751075     */
    10761076    $block_template = apply_filters( 'pre_get_block_template', null, $id, $template_type );
    … …  
    11171117     *
    11181118     * @param WP_Block_Template|null $block_template The found block template, or null if there isn't one.
    1119      * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
    1120      * @param array                  $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
     1119     * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
     1120     * @param array                  $template_type  Template type: 'wp_template' or 'wp_template_part'.
    11211121     */
    11221122    return apply_filters( 'get_block_template', $block_template, $id, $template_type );
    … …  
    11301130 * @since 5.9.0
    11311131 *
    1132  * @param string $id            Template unique identifier (example: theme_slug//template_slug).
    1133  * @param string $template_type Optional. Template type: `'wp_template'` or '`wp_template_part'`.
    1134  *                              Default `'wp_template'`.
     1132 * @param string $id            Template unique identifier (example: 'theme_slug//template_slug').
     1133 * @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
     1134 *                              Default 'wp_template'.
    11351135 * @return WP_Block_Template|null The found block template, or null if there isn't one.
    11361136 */
    … …  
    11451145     * @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
    11461146     *                                               or null to allow WP to run its normal queries.
    1147      * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
    1148      * @param string                 $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
     1147     * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
     1148     * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
    11491149     */
    11501150    $block_template = apply_filters( 'pre_get_block_file_template', null, $id, $template_type );
    … …  
    11791179     *
    11801180     * @param WP_Block_Template|null $block_template The found block template, or null if there is none.
    1181      * @param string                 $id             Template unique identifier (example: theme_slug//template_slug).
    1182      * @param string                 $template_type  Template type: `'wp_template'` or '`wp_template_part'`.
     1181     * @param string                 $id             Template unique identifier (example: 'theme_slug//template_slug').
     1182     * @param string                 $template_type  Template type: 'wp_template' or 'wp_template_part'.
    11831183     */
    11841184    return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );

  • trunk/src/wp-includes/class-wp-post-type.php

    r54318 r55694  
    411411     * @param string       $post_type Post type key.
    412412     * @param array|string $args      Optional. Array or string of arguments for registering a post type.
     413     *                                See register_post_type() for information on accepted arguments.
    413414     *                                Default empty array.
    414415     */

  • trunk/src/wp-includes/class-wp-taxonomy.php

    r54877 r55694  
    282282     * @param array|string $object_type Name of the object type for the taxonomy object.
    283283     * @param array|string $args        Optional. Array or query string of arguments for registering a taxonomy.
     284     *                                  See register_taxonomy() for information on accepted arguments.
    284285     *                                  Default empty array.
    285286     */

  • trunk/src/wp-includes/class-wp-theme-json-resolver.php

    r55448 r55694  
    1414 * This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
    1515 * This is a low-level API that may need to do breaking changes. Please,
    16  * use get_global_settings, get_global_styles, and get_global_stylesheet instead.
     16 * use get_global_settings(), get_global_styles(), and get_global_stylesheet() instead.
    1717 *
    1818 * @access private
    … …  
    387387    /**
    388388     * Returns the custom post type that contains the user's origin config
    389      * for the active theme or a void array if none are found.
     389     * for the active theme or an empty array if none are found.
    390390     *
    391391     * This can also create and return a new draft custom post type.

  • trunk/src/wp-includes/class-wpdb.php

    r55431 r55694  
    25572557     * @param string       $table  Table name.
    25582558     * @param array        $data   Data to insert (in column => value pairs).
    2559      *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     2559     *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
    25602560     *                             Sending a null value will cause the column to be set to NULL - the corresponding
    25612561     *                             format is ignored in this case.
    2562      * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
    2563      *                             If string, that format will be used for all of the values in $data.
     2562     * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
     2563     *                             If string, that format will be used for all of the values in `$data`.
    25642564     *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2565      *                             If omitted, all values in $data will be treated as strings unless otherwise
     2565     *                             If omitted, all values in `$data` will be treated as strings unless otherwise
    25662566     *                             specified in wpdb::$field_types. Default null.
    25672567     * @return int|false The number of rows inserted, or false on error.
    … …  
    25872587     * @param string       $table  Table name.
    25882588     * @param array        $data   Data to insert (in column => value pairs).
    2589      *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     2589     *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
    25902590     *                             Sending a null value will cause the column to be set to NULL - the corresponding
    25912591     *                             format is ignored in this case.
    2592      * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
    2593      *                             If string, that format will be used for all of the values in $data.
     2592     * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
     2593     *                             If string, that format will be used for all of the values in `$data`.
    25942594     *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2595      *                             If omitted, all values in $data will be treated as strings unless otherwise
     2595     *                             If omitted, all values in `$data` will be treated as strings unless otherwise
    25962596     *                             specified in wpdb::$field_types. Default null.
    25972597     * @return int|false The number of rows affected, or false on error.
    … …  
    26042604     * Helper function for insert and replace.
    26052605     *
    2606      * Runs an insert or replace query based on $type argument.
     2606     * Runs an insert or replace query based on `$type` argument.
    26072607     *
    26082608     * @since 3.0.0
    … …  
    26142614     * @param string       $table  Table name.
    26152615     * @param array        $data   Data to insert (in column => value pairs).
    2616      *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     2616     *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
    26172617     *                             Sending a null value will cause the column to be set to NULL - the corresponding
    26182618     *                             format is ignored in this case.
    2619      * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
    2620      *                             If string, that format will be used for all of the values in $data.
     2619     * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
     2620     *                             If string, that format will be used for all of the values in `$data`.
    26212621     *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2622      *                             If omitted, all values in $data will be treated as strings unless otherwise
     2622     *                             If omitted, all values in `$data` will be treated as strings unless otherwise
    26232623     *                             specified in wpdb::$field_types. Default null.
    2624      * @param string       $type   Optional. Type of operation. Possible values include 'INSERT' or 'REPLACE'.
     2624     * @param string       $type   Optional. Type of operation. Either 'INSERT' or 'REPLACE'.
    26252625     *                             Default 'INSERT'.
    26262626     * @return int|false The number of rows affected, or false on error.

  • trunk/src/wp-includes/http.php

    r55693 r55694  
    4040 * @param string $url  URL to retrieve.
    4141 * @param array  $args Optional. Request arguments. Default empty array.
     42 *                     See WP_Http::request() for information on accepted arguments.
    4243 * @return array|WP_Error The response or WP_Error on failure.
    4344 */
    … …  
    6162 * @param string $url  URL to retrieve.
    6263 * @param array  $args Optional. Request arguments. Default empty array.
     64 *                     See WP_Http::request() for information on accepted arguments.
    6365 * @return array|WP_Error The response or WP_Error on failure.
    6466 */
    … …  
    8284 * @param string $url  URL to retrieve.
    8385 * @param array  $args Optional. Request arguments. Default empty array.
     86 *                     See WP_Http::request() for information on accepted arguments.
    8487 * @return array|WP_Error The response or WP_Error on failure.
    8588 */
    … …  
    103106 * @param string $url  URL to retrieve.
    104107 * @param array  $args Optional. Request arguments. Default empty array.
     108 *                     See WP_Http::request() for information on accepted arguments.
    105109 * @return array|WP_Error The response or WP_Error on failure.
    106110 */
    … …  
    126130 * @param string $url  URL to retrieve.
    127131 * @param array  $args Optional. Request arguments. Default empty array.
     132 *                     See WP_Http::request() for information on accepted arguments.
    128133 * @return array|WP_Error {
    129134 *     The response array or a WP_Error on failure.
    … …  
    156161 * @param string $url  URL to retrieve.
    157162 * @param array  $args Optional. Request arguments. Default empty array.
     163 *                     See WP_Http::request() for information on accepted arguments.
    158164 * @return array|WP_Error The response or WP_Error on failure.
    159165 */
    … …  
    173179 * @param string $url  URL to retrieve.
    174180 * @param array  $args Optional. Request arguments. Default empty array.
     181 *                     See WP_Http::request() for information on accepted arguments.
    175182 * @return array|WP_Error The response or WP_Error on failure.
    176183 */
    … …  
    190197 * @param string $url  URL to retrieve.
    191198 * @param array  $args Optional. Request arguments. Default empty array.
     199 *                     See WP_Http::request() for information on accepted arguments.
    192200 * @return array|WP_Error The response or WP_Error on failure.
    193201 */

  • trunk/src/wp-includes/plugin.php

    r53809 r55694  
    576576 * @since 2.5.0
    577577 *
    578  * @see has_filter() has_action() is an alias of has_filter().
     578 * @see has_filter() This function is an alias of has_filter().
    579579 *
    580580 * @param string                      $hook_name The name of the action hook.
    … …  
    965965
    966966/**
    967  * Builds Unique ID for storage and retrieval.
    968  *
    969  * The old way to serialize the callback caused issues and this function is the
    970  * solution. It works by checking for objects and creating a new property in
    971  * the class to keep track of the object and new objects of the same class that
    972  * need to be added.
    973  *
    974  * It also allows for the removal of actions and filters for objects after they
    975  * change class properties. It is possible to include the property $wp_filter_id
    976  * in your class and set it to "null" or a number to bypass the workaround.
    977  * However this will prevent you from adding new classes and any new classes
    978  * will overwrite the previous hook by the same class.
     967 * Builds a unique string ID for a hook callback function.
    979968 *
    980969 * Functions and static method callbacks are just returned as strings and

  • trunk/src/wp-includes/post-template.php

    r55652 r55694  
    3838 * @param string $after   Optional. Markup to append to the title. Default empty.
    3939 * @param bool   $display Optional. Whether to echo or return the title. Default true for echo.
    40  * @return void|string Void if `$display` argument is true, current post title if `$display` is false.
     40 * @return void|string Void if `$display` argument is true or the title is empty,
     41 *                     current post title if `$display` is false.
    4142 */
    4243function the_title( $before = '', $after = '', $display = true ) {

  • trunk/src/wp-includes/post.php

    r55677 r55694  
    61406140 * @param string|array $args             Arguments for inserting an attachment.
    61416141 * @param string|false $file             Optional. Filename. Default false.
    6142  * @param int          $parent_post_id   Optional. Parent post ID. Default 0.
     6142 * @param int          $parent_post_id   Optional. Parent post ID or 0 for no parent. Default 0.
    61436143 * @param bool         $wp_error         Optional. Whether to return a WP_Error on failure. Default false.
    61446144 * @param bool         $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true.

  • trunk/src/wp-includes/theme.php

    r55677 r55694  
    825825    /**
    826826     * Fires after the theme is switched.
     827     *
     828     * See {@see 'after_switch_theme'}.
    827829     *
    828830     * @since 1.5.0
    … …  
    33873389        if ( $old_theme->exists() ) {
    33883390            /**
    3389              * Fires on the first WP load after a theme switch if the old theme still exists.
     3391             * Fires on the next WP load after the theme has been switched.
    33903392             *
    3391              * This action fires multiple times and the parameters differs
    3392              * according to the context, if the old theme exists or not.
    3393              * If the old theme is missing, the parameter will be the slug
     3393             * The parameters differ according to whether the old theme exists or not.
     3394             * If the old theme is missing, the old name will instead be the slug
    33943395             * of the old theme.
     3396             *
     3397             * See {@see 'switch_theme'}.
    33953398             *
    33963399             * @since 3.3.0
Note: See TracChangeset for help on using the changeset viewer.