Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-06-22 21:04:57 +02:00
Code Issues Projects Releases Wiki Activity

Docs: Correct and improve various inline documentation.

Browse Source 
See #42505

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


git-svn-id: http://core.svn.wordpress.org/trunk@43411 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2018-08-27 14:28:26 +00:00
parent 5bbb3b38d9
commit 47d32decd6
11 changed files with 61 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
wp-admin/includes/post.php
View File

@ -1519,9 +1519,9 @@ function _wp_post_thumbnail_html( $thumbnail_id = null, $post = null ) {
* @since 3.5.0 Added the `$post_id` parameter.
* @since 4.6.0 Added the `$thumbnail_id` parameter.
*
* @param string $content Admin post thumbnail HTML markup.
* @param int $post_id Post ID.
* @param int $thumbnail_id Thumbnail ID.
* @param string $content Admin post thumbnail HTML markup.
* @param int $post_id Post ID.
* @param int|null $thumbnail_id Thumbnail attachment ID, or null if there isn't one.
*/
return apply_filters( 'admin_post_thumbnail_html', $content, $post->ID, $thumbnail_id );
}

6
wp-includes/class-wp-query.php
View File

@ -1686,14 +1686,14 @@ class WP_Query {
}
/**
* Retrieve the posts based on query variables.
* Retrieves an array of posts based on query variables.
*
* There are a few filters and actions that can be used to modify the post
* database query.
*
* @since 1.5.0
*
* @return array List of posts.
* @return WP_Post[]|int[] Array of post objects or post IDs.
*/
public function get_posts() {
global $wpdb;
@ -3357,7 +3357,7 @@ class WP_Query {
* @since 1.5.0
*
* @param string|array $query URL query string or array of query arguments.
* @return array List of posts.
* @return WP_Post[]|int[] Array of post objects or post IDs.
*/
public function query( $query ) {
$this->init();

29
wp-includes/class-wp-user.php
View File

@ -80,7 +80,8 @@ class WP_User {
* All capabilities the user has, including individual and role based.
*
* @since 2.0.0
* @var array
* @var bool[] Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
*/
public $allcaps = array();
@ -478,16 +479,15 @@ class WP_User {
}
/**
* Retrieve all of the role capabilities and merge with individual capabilities.
* Retrieves all of the capabilities of the roles of the user, and merges them with individual user capabilities.
*
* All of the capabilities of the roles the user belongs to are merged with
* user's individual capabilities. This also means that the user can be denied
* specific capabilities that their role might have, but the user isn't granted
* permission to.
* All of the capabilities of the roles of the user are merged with the user's individual capabilities. This means
* that the user can be denied specific capabilities that their role might have, but the user is specifically denied.
*
* @since 2.0.0
*
* @return array List of all capabilities for the user.
* @return bool[] Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
*/
public function get_role_caps() {
$switch_site = false;
@ -751,11 +751,18 @@ class WP_User {
* Dynamically filter a user's capabilities.
*
* @since 2.0.0
* @since 3.7.0 Added the user object.
* @since 3.7.0 Added the `$user` parameter.
*
* @param bool[] $allcaps An array of all the user's capabilities.
* @param string[] $caps Actual capabilities for meta capability.
* @param array $args Optional parameters passed to has_cap(), typically object ID.
* @param bool[] $allcaps Array of key/value pairs where keys represent a capability name and boolean values
* represent whether the user has that capability.
* @param string[] $caps Required primitive capabilities for the requested capability.
* @param array $args {
* Arguments that accompany the requested capability check.
*
* @type string $0 Requested capability.
* @type int $1 Concerned user ID.
* @type mixed ...$2 Optional second and further parameters, typically object ID.
* }
* @param WP_User $user The user object.
*/
$capabilities = apply_filters( 'user_has_cap', $this->allcaps, $caps, $args, $this );

4
wp-includes/general-template.php
View File

@ -2904,11 +2904,11 @@ function wp_site_icon() {
}
/**
* Filters the site icon meta tags, so Plugins can add their own.
* Filters the site icon meta tags, so plugins can add their own.
*
* @since 4.3.0
*
* @param array $meta_tags Site Icon meta elements.
* @param string[] $meta_tags Array of Site Icon meta tags.
*/
$meta_tags = apply_filters( 'site_icon_meta_tags', $meta_tags );
$meta_tags = array_filter( $meta_tags );

3
wp-includes/js/media-editor.js
View File

@ -609,8 +609,7 @@
return wp.media.view.settings.post.featuredImageId;
},
/**
* Set the featured image id, save the post thumbnail data and
* set the HTML in the post meta box to the new featured image.
* Sets the featured image ID property and sets the HTML in the post meta box to the new featured image.
*
* @param {number} id The post ID of the featured image, or -1 to unset it.
*/

6
wp-includes/media.php
View File

@ -3414,9 +3414,9 @@ function wp_prepare_attachment_for_js( $attachment ) {
*
* @since 3.5.0
*
* @param array $response Array of prepared attachment data.
* @param WP_Post $attachment Attachment object.
* @param array $meta Array of attachment meta data.
* @param array $response Array of prepared attachment data.
* @param WP_Post $attachment Attachment object.
* @param array|false $meta Array of attachment meta data, or false if there is none.
*/
return apply_filters( 'wp_prepare_attachment_for_js', $response, $attachment, $meta );
}

3
wp-includes/meta.php
View File

@ -150,7 +150,8 @@ function add_metadata( $meta_type, $object_id, $meta_key, $meta_value, $unique =
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. If specified, only update existing metadata entries with
* the specified value. Otherwise, update all entries.
* @return int|bool Meta ID if the key didn't exist, true on successful update, false on failure.
* @return int|bool The new meta field ID if a field with the given key didn't exist and was
* therefore added, true on successful update, false on failure.
*/
function update_metadata( $meta_type, $object_id, $meta_key, $meta_value, $prev_value = '' ) {
global $wpdb;

42
wp-includes/post.php
View File

@ -1823,7 +1823,7 @@ function is_post_type_viewable( $post_type ) {
}
/**
* Retrieve list of latest posts or posts matching criteria.
* Retrieves an array of the latest posts, or posts matching the given criteria.
*
* The defaults are as follows:
*
@ -1844,7 +1844,7 @@ function is_post_type_viewable( $post_type ) {
* @type array $exclude An array of post IDs not to retrieve. Default empty array.
* @type bool $suppress_filters Whether to suppress filters. Default true.
* }
* @return array List of posts.
* @return WP_Post[]|int[] Array of post objects or post IDs.
*/
function get_posts( $args = null ) {
$defaults = array(
@ -1891,7 +1891,7 @@ function get_posts( $args = null ) {
//
/**
* Add meta data field to a post.
* Adds a meta field to the given post.
*
* Post meta data is called "Custom Fields" on the Administration Screen.
*
@ -1918,11 +1918,11 @@ function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
}
/**
* Remove metadata matching criteria from a post.
* Deletes a post meta field for the given post ID.
*
* You can match based on the key, or key and value. Removing based on key and
* value, will keep from removing duplicate metadata with the same key. It also
* allows removing all metadata matching key, if needed.
* allows removing all metadata matching the key, if needed.
*
* @since 1.5.0
*
@ -1946,17 +1946,16 @@ function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {
}
/**
* Retrieve post meta field for a post.
* Retrieves a post meta field for the given post ID.
*
* @since 1.5.0
*
* @param int $post_id Post ID.
* @param string $key Optional. The meta key to retrieve. By default, returns
* data for all keys. Default empty.
* @param bool $single Optional, default is false.
* If true, return only the first value of the specified meta_key.
* This parameter has no effect if meta_key is not specified.
* @return mixed Will be an array if $single is false. Will be value of meta data
* @param bool $single Optional. If true, returns only the first value for the specified meta key.
* This parameter has no effect if $key is not specified. Default false.
* @return mixed Will be an array if $single is false. Will be value of the meta
* field if $single is true.
*/
function get_post_meta( $post_id, $key = '', $single = false ) {
@ -1964,22 +1963,21 @@ function get_post_meta( $post_id, $key = '', $single = false ) {
}
/**
* Update post meta field based on post ID.
* Updates a post meta field based on the given post ID.
*
* Use the $prev_value parameter to differentiate between meta fields with the
* same key and post ID.
*
* If the meta field for the post does not exist, it will be added.
* If the meta field for the post does not exist, it will be added and its ID returned.
*
* @since 1.5.0
*
* @param int $post_id Post ID.
* @param string $meta_key Metadata key.
* @param mixed $meta_value Metadata value. Must be serializable if non-scalar.
* @param mixed $prev_value Optional. Previous value to check before removing.
* Default empty.
* @return int|bool Meta ID if the key didn't exist, true on successful update,
* false on failure.
* @param mixed $prev_value Optional. Previous value to check before updating.
* @return int|bool The new meta field ID if a field with the given key didn't exist and was
* therefore added, true on successful update, false on failure.
*/
function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' ) {
// Make sure meta is added to the post, not a revision.
@ -1995,7 +1993,7 @@ function update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' )
}
/**
* Delete everything from post meta matching meta key.
* Deletes everything from post meta matching the given meta key.
*
* @since 2.3.0
*
@ -6490,12 +6488,12 @@ function _publish_post_hook( $post_id ) {
}
/**
* Return the post's parent post ID.
* Returns the ID of the post's parent.
*
* @since 3.1.0
*
* @param int|WP_Post $post Post ID or post object. Defaults to global $post.
* @return int|false Post parent ID, otherwise false.
* @return int|false Post parent ID (which can be 0 if there is no parent), or false if the post does not exist.
*/
function wp_get_post_parent_id( $post ) {
$post = get_post( $post );
@ -6559,7 +6557,7 @@ function wp_check_post_hierarchy_for_loops( $post_parent, $post_ID ) {
}
/**
* Set a post thumbnail.
* Sets the post thumbnail (featured image) for the given post.
*
* @since 3.1.0
*
@ -6581,11 +6579,11 @@ function set_post_thumbnail( $post, $thumbnail_id ) {
}
/**
* Remove a post thumbnail.
* Removes the thumbnail (featured image) from the given post.
*
* @since 3.3.0
*
* @param int|WP_Post $post Post ID or post object where thumbnail should be removed from.
* @param int|WP_Post $post Post ID or post object from which the thumbnail should be removed.
* @return bool True on success, false on failure.
*/
function delete_post_thumbnail( $post ) {

2
wp-includes/rest-api/class-wp-rest-response.php
View File

@ -193,7 +193,7 @@ class WP_REST_Response extends WP_HTTP_Response {
}
/**
* Retrieves the handler that was responsible for generating the response.
* Sets the handler that was responsible for generating the response.
*
* @since 4.4.0
*

14
wp-includes/rest-api/class-wp-rest-server.php
View File

@ -904,9 +904,9 @@ class WP_REST_Server {
*
* @since 4.7.0
*
* @param WP_HTTP_Response $response Result to send to the client. Usually a WP_REST_Response.
* @param WP_REST_Server $handler ResponseHandler instance (usually WP_REST_Server).
* @param WP_REST_Request $request Request used to generate the response.
* @param WP_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
* @param array $handler Route handler used for the request.
* @param WP_REST_Request $request Request used to generate the response.
*/
$response = apply_filters( 'rest_request_before_callbacks', $response, $handler, $request );
@ -932,7 +932,7 @@ class WP_REST_Server {
* @since 4.4.0
* @since 4.5.0 Added `$route` and `$handler` parameters.
*
* @param bool $dispatch_result Dispatch result, will be used if not empty.
* @param mixed $dispatch_result Dispatch result, will be used if not empty.
* @param WP_REST_Request $request Request used to generate the response.
* @param string $route Route matched for the request.
* @param array $handler Route handler used for the request.
@ -963,9 +963,9 @@ class WP_REST_Server {
*
* @since 4.7.0
*
* @param WP_HTTP_Response $response Result to send to the client. Usually a WP_REST_Response.
* @param WP_REST_Server $handler ResponseHandler instance (usually WP_REST_Server).
* @param WP_REST_Request $request Request used to generate the response.
* @param WP_HTTP_Response|WP_Error $response Result to send to the client. Usually a WP_REST_Response or WP_Error.
* @param array $handler Route handler used for the request.
* @param WP_REST_Request $request Request used to generate the response.
*/
$response = apply_filters( 'rest_request_after_callbacks', $response, $handler, $request );

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '5.0-alpha-43581';
$wp_version = '5.0-alpha-43582';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.