Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-12-22 17:18:32 +01:00
Code Issues Projects Releases Wiki Activity

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

Browse Source 
See #57840

Built from https://develop.svn.wordpress.org/trunk@55694


git-svn-id: http://core.svn.wordpress.org/trunk@55206 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2023-04-27 23:15:17 +00:00
parent cc24b047eb
commit f14f3ba995
13 changed files with 80 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
wp-admin/includes/ms.php
View File

@ -130,12 +130,17 @@ function wpmu_delete_blog( $blog_id, $drop = false ) {
}
/**
* Deletes a user from the network and remove from all sites.
* Deletes a user and all of their posts from the network.
*
* This function:
*
* - Deletes all posts (of all post types) authored by the user on all sites on the network
* - Deletes all links owned by the user on all sites on the network
* - Removes the user from all sites on the network
* - Deletes the user from the database
*
* @since 3.0.0
*
* @todo Merge with wp_delete_user()?
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param int $id The user ID.

22
wp-admin/includes/user.php
View File

@ -324,12 +324,15 @@ function get_users_drafts( $user_id ) {
}
/**
* Remove user and optionally reassign posts and links to another user.
* Delete user and optionally reassign posts and links to another user.
*
* If the $reassign parameter is not assigned to a User ID, then all posts will
* be deleted of that user. The action {@see 'delete_user'} that is passed the User ID
* Note that on a Multisite installation the user only gets removed from the site
* and does not get deleted from the database.
*
* If the `$reassign` parameter is not assigned to a user ID, then all posts will
* be deleted of that user. The action {@see 'delete_user'} that is passed the user ID
* being deleted will be run after the posts are either reassigned or deleted.
* The user meta will also be deleted that are for that User ID.
* The user meta will also be deleted that are for that user ID.
*
* @since 2.0.0
*
@ -361,7 +364,10 @@ function wp_delete_user( $id, $reassign = null ) {
}
/**
* Fires immediately before a user is deleted from the database.
* Fires immediately before a user is deleted from the site.
*
* Note that on a Multisite installation the user only gets removed from the site
* and does not get deleted from the database.
*
* @since 2.0.0
* @since 5.5.0 Added the `$user` parameter.
@ -440,7 +446,11 @@ function wp_delete_user( $id, $reassign = null ) {
clean_user_cache( $user );
/**
* Fires immediately after a user is deleted from the database.
* Fires immediately after a user is deleted from the site.
*
* Note that on a Multisite installation the user may not have been deleted from
* the database depending on whether `wp_delete_user()` or `wpmu_delete_user()`
* was called.
*
* @since 2.9.0
* @since 5.5.0 Added the `$user` parameter.

32
wp-includes/block-template-utils.php
View File

@ -299,7 +299,7 @@ function _get_block_template_file( $template_type, $slug ) {
*
* @type array $slug__in List of slugs to include.
* @type array $slug__not_in List of slugs to skip.
* @type string $area A 'wp_template_part_area' taxonomy value to filter by (for wp_template_part template type only).
* @type string $area A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
* @type string $post_type Post type to get the templates for.
* }
*
@ -755,7 +755,7 @@ function _wp_build_title_and_description_for_taxonomy_block_template( $taxonomy,
* @access private
*
* @param WP_Post $post Template post.
* @return WP_Block_Template|WP_Error Template.
* @return WP_Block_Template|WP_Error Template or error object.
*/
function _build_block_template_result_from_post( $post ) {
$default_template_types = get_default_block_template_types();
@ -1055,9 +1055,9 @@ function get_block_templates( $query = array(), $template_type = 'wp_template' )
*
* @since 5.8.0
*
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type Optional. Template type: `'wp_template'` or '`wp_template_part'`.
* Default `'wp_template'`.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
* Default 'wp_template'.
* @return WP_Block_Template|null Template.
*/
function get_block_template( $id, $template_type = 'wp_template' ) {
@ -1070,8 +1070,8 @@ function get_block_template( $id, $template_type = 'wp_template' ) {
*
* @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
* or null to allow WP to run its normal queries.
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type Template type: `'wp_template'` or '`wp_template_part'`.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Template type: 'wp_template' or 'wp_template_part'.
*/
$block_template = apply_filters( 'pre_get_block_template', null, $id, $template_type );
if ( ! is_null( $block_template ) ) {
@ -1116,8 +1116,8 @@ function get_block_template( $id, $template_type = 'wp_template' ) {
* @since 5.9.0
*
* @param WP_Block_Template|null $block_template The found block template, or null if there isn't one.
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param array $template_type Template type: `'wp_template'` or '`wp_template_part'`.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param array $template_type Template type: 'wp_template' or 'wp_template_part'.
*/
return apply_filters( 'get_block_template', $block_template, $id, $template_type );
}
@ -1129,9 +1129,9 @@ function get_block_template( $id, $template_type = 'wp_template' ) {
*
* @since 5.9.0
*
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type Optional. Template type: `'wp_template'` or '`wp_template_part'`.
* Default `'wp_template'`.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Optional. Template type: 'wp_template' or 'wp_template_part'.
* Default 'wp_template'.
* @return WP_Block_Template|null The found block template, or null if there isn't one.
*/
function get_block_file_template( $id, $template_type = 'wp_template' ) {
@ -1144,8 +1144,8 @@ function get_block_file_template( $id, $template_type = 'wp_template' ) {
*
* @param WP_Block_Template|null $block_template Return block template object to short-circuit the default query,
* or null to allow WP to run its normal queries.
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type Template type: `'wp_template'` or '`wp_template_part'`.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Template type: 'wp_template' or 'wp_template_part'.
*/
$block_template = apply_filters( 'pre_get_block_file_template', null, $id, $template_type );
if ( ! is_null( $block_template ) ) {
@ -1178,8 +1178,8 @@ function get_block_file_template( $id, $template_type = 'wp_template' ) {
* @since 5.9.0
*
* @param WP_Block_Template|null $block_template The found block template, or null if there is none.
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type Template type: `'wp_template'` or '`wp_template_part'`.
* @param string $id Template unique identifier (example: 'theme_slug//template_slug').
* @param string $template_type Template type: 'wp_template' or 'wp_template_part'.
*/
return apply_filters( 'get_block_file_template', $block_template, $id, $template_type );
}

1
wp-includes/class-wp-post-type.php
View File

@ -410,6 +410,7 @@ final class WP_Post_Type {
*
* @param string $post_type Post type key.
* @param array|string $args Optional. Array or string of arguments for registering a post type.
* See register_post_type() for information on accepted arguments.
* Default empty array.
*/
public function __construct( $post_type, $args = array() ) {

1
wp-includes/class-wp-taxonomy.php
View File

@ -281,6 +281,7 @@ final class WP_Taxonomy {
* @param string $taxonomy Taxonomy key, must not exceed 32 characters.
* @param array|string $object_type Name of the object type for the taxonomy object.
* @param array|string $args Optional. Array or query string of arguments for registering a taxonomy.
* See register_taxonomy() for information on accepted arguments.
* Default empty array.
*/
public function __construct( $taxonomy, $object_type, $args = array() ) {

4
wp-includes/class-wp-theme-json-resolver.php
View File

@ -13,7 +13,7 @@
*
* This class is for internal core usage and is not supposed to be used by extenders (plugins and/or themes).
* This is a low-level API that may need to do breaking changes. Please,
* use get_global_settings, get_global_styles, and get_global_stylesheet instead.
* use get_global_settings(), get_global_styles(), and get_global_stylesheet() instead.
*
* @access private
*/
@ -386,7 +386,7 @@ class WP_Theme_JSON_Resolver {
/**
* Returns the custom post type that contains the user's origin config
* for the active theme or a void array if none are found.
* for the active theme or an empty array if none are found.
*
* This can also create and return a new draft custom post type.
*

28
wp-includes/class-wpdb.php
View File

@ -2556,13 +2556,13 @@ class wpdb {
*
* @param string $table Table name.
* @param array $data Data to insert (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped).
* Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
* Sending a null value will cause the column to be set to NULL - the corresponding
* format is ignored in this case.
* @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
* If string, that format will be used for all of the values in $data.
* @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
* If string, that format will be used for all of the values in `$data`.
* A format is one of '%d', '%f', '%s' (integer, float, string).
* If omitted, all values in $data will be treated as strings unless otherwise
* If omitted, all values in `$data` will be treated as strings unless otherwise
* specified in wpdb::$field_types. Default null.
* @return int|false The number of rows inserted, or false on error.
*/
@ -2586,13 +2586,13 @@ class wpdb {
*
* @param string $table Table name.
* @param array $data Data to insert (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped).
* Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
* Sending a null value will cause the column to be set to NULL - the corresponding
* format is ignored in this case.
* @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
* If string, that format will be used for all of the values in $data.
* @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
* If string, that format will be used for all of the values in `$data`.
* A format is one of '%d', '%f', '%s' (integer, float, string).
* If omitted, all values in $data will be treated as strings unless otherwise
* If omitted, all values in `$data` will be treated as strings unless otherwise
* specified in wpdb::$field_types. Default null.
* @return int|false The number of rows affected, or false on error.
*/
@ -2603,7 +2603,7 @@ class wpdb {
/**
* Helper function for insert and replace.
*
* Runs an insert or replace query based on $type argument.
* Runs an insert or replace query based on `$type` argument.
*
* @since 3.0.0
*
@ -2613,15 +2613,15 @@ class wpdb {
*
* @param string $table Table name.
* @param array $data Data to insert (in column => value pairs).
* Both $data columns and $data values should be "raw" (neither should be SQL escaped).
* Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
* Sending a null value will cause the column to be set to NULL - the corresponding
* format is ignored in this case.
* @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
* If string, that format will be used for all of the values in $data.
* @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
* If string, that format will be used for all of the values in `$data`.
* A format is one of '%d', '%f', '%s' (integer, float, string).
* If omitted, all values in $data will be treated as strings unless otherwise
* If omitted, all values in `$data` will be treated as strings unless otherwise
* specified in wpdb::$field_types. Default null.
* @param string $type Optional. Type of operation. Possible values include 'INSERT' or 'REPLACE'.
* @param string $type Optional. Type of operation. Either 'INSERT' or 'REPLACE'.
* Default 'INSERT'.
* @return int|false The number of rows affected, or false on error.
*/

8
wp-includes/http.php
View File

@ -39,6 +39,7 @@ function _wp_http_get_object() {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_request( $url, $args = array() ) {
@ -60,6 +61,7 @@ function wp_safe_remote_request( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_get( $url, $args = array() ) {
@ -81,6 +83,7 @@ function wp_safe_remote_get( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_post( $url, $args = array() ) {
@ -102,6 +105,7 @@ function wp_safe_remote_post( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_safe_remote_head( $url, $args = array() ) {
@ -125,6 +129,7 @@ function wp_safe_remote_head( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error {
* The response array or a WP_Error on failure.
*
@ -155,6 +160,7 @@ function wp_remote_request( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_remote_get( $url, $args = array() ) {
@ -172,6 +178,7 @@ function wp_remote_get( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_remote_post( $url, $args = array() ) {
@ -189,6 +196,7 @@ function wp_remote_post( $url, $args = array() ) {
*
* @param string $url URL to retrieve.
* @param array $args Optional. Request arguments. Default empty array.
* See WP_Http::request() for information on accepted arguments.
* @return array|WP_Error The response or WP_Error on failure.
*/
function wp_remote_head( $url, $args = array() ) {

15
wp-includes/plugin.php
View File

@ -575,7 +575,7 @@ function do_action_ref_array( $hook_name, $args ) {
*
* @since 2.5.0
*
* @see has_filter() has_action() is an alias of has_filter().
* @see has_filter() This function is an alias of has_filter().
*
* @param string $hook_name The name of the action hook.
* @param callable|string|array|false $callback Optional. The callback to check for.
@ -964,18 +964,7 @@ function _wp_call_all_hook( $args ) {
}
/**
* Builds Unique ID for storage and retrieval.
*
* The old way to serialize the callback caused issues and this function is the
* solution. It works by checking for objects and creating a new property in
* the class to keep track of the object and new objects of the same class that
* need to be added.
*
* It also allows for the removal of actions and filters for objects after they
* change class properties. It is possible to include the property $wp_filter_id
* in your class and set it to "null" or a number to bypass the workaround.
* However this will prevent you from adding new classes and any new classes
* will overwrite the previous hook by the same class.
* Builds a unique string ID for a hook callback function.
*
* Functions and static method callbacks are just returned as strings and
* shouldn't have any speed penalty.

3
wp-includes/post-template.php
View File

@ -37,7 +37,8 @@ function get_the_ID() { // phpcs:ignore WordPress.NamingConventions.ValidFunctio
* @param string $before Optional. Markup to prepend to the title. Default empty.
* @param string $after Optional. Markup to append to the title. Default empty.
* @param bool $display Optional. Whether to echo or return the title. Default true for echo.
* @return void|string Void if `$display` argument is true, current post title if `$display` is false.
* @return void|string Void if `$display` argument is true or the title is empty,
* current post title if `$display` is false.
*/
function the_title( $before = '', $after = '', $display = true ) {
$title = get_the_title();

2
wp-includes/post.php
View File

@ -6139,7 +6139,7 @@ function is_local_attachment( $url ) {
*
* @param string|array $args Arguments for inserting an attachment.
* @param string|false $file Optional. Filename. Default false.
* @param int $parent_post_id Optional. Parent post ID. Default 0.
* @param int $parent_post_id Optional. Parent post ID or 0 for no parent. Default 0.
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
* @param bool $fire_after_hooks Optional. Whether to fire the after insert hooks. Default true.
* @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure.

11
wp-includes/theme.php
View File

@ -825,6 +825,8 @@ function switch_theme( $stylesheet ) {
/**
* Fires after the theme is switched.
*
* See {@see 'after_switch_theme'}.
*
* @since 1.5.0
* @since 4.5.0 Introduced the `$old_theme` parameter.
*
@ -3386,13 +3388,14 @@ function check_theme_switched() {
if ( $old_theme->exists() ) {
/**
* Fires on the first WP load after a theme switch if the old theme still exists.
* Fires on the next WP load after the theme has been switched.
*
* This action fires multiple times and the parameters differs
* according to the context, if the old theme exists or not.
* If the old theme is missing, the parameter will be the slug
* The parameters differ according to whether the old theme exists or not.
* If the old theme is missing, the old name will instead be the slug
* of the old theme.
*
* See {@see 'switch_theme'}.
*
* @since 3.3.0
*
* @param string $old_name Old theme name.

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
$wp_version = '6.3-alpha-55693';
$wp_version = '6.3-alpha-55694';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.