Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-12-23 01:27:36 +01:00
Code Issues Projects Releases Wiki Activity

Docs: Miscellaneous docblock fixes and improvements.

Browse Source 
See #48303

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


git-svn-id: http://core.svn.wordpress.org/trunk@46391 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2019-10-26 20:43:04 +00:00
parent 552852d887
commit 7c2b9f2a2e
8 changed files with 102 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1319,7 +1319,12 @@ function postbox_classes( $box_id, $screen_id ) {
* @param int $id Post ID or post object. * @param int $id Post ID or post object.
* @param string $title Optional. Title to override the post's current title when generating the post name. Default null. * @param string $title Optional. Title to override the post's current title when generating the post name. Default null.
* @param string $name Optional. Name to override the post name. Default null. * @param string $name Optional. Name to override the post name. Default null.
* @return array Array containing the sample permalink with placeholder for the post name, and the post name. * @return array {
* Array containing the sample permalink with placeholder for the post name, and the post name.
*
* @type string $0 The permalink with placeholder for the post name.
* @type string $1 The post name.
* }
*/ */
function get_sample_permalink( $id, $title = null, $name = null ) { function get_sample_permalink( $id, $title = null, $name = null ) {
$post = get_post( $id ); $post = get_post( $id );
@ -1383,7 +1388,12 @@ function get_sample_permalink( $id, $title = null, $name = null ) {
* *
* @since 4.4.0 * @since 4.4.0
* *
* @param array $permalink Array containing the sample permalink with placeholder for the post name, and the post name. * @param array $permalink {
* Array containing the sample permalink with placeholder for the post name, and the post name.
*
* @type string $0 The permalink with placeholder for the post name.
* @type string $1 The post name.
* }
* @param int $post_id Post ID. * @param int $post_id Post ID.
* @param string $title Post title. * @param string $title Post title.
* @param string $name Post name (slug). * @param string $name Post name (slug).
@ -1637,17 +1647,16 @@ function _admin_notice_post_locked() {
} }
if ( $user ) { if ( $user ) {
/** /**
* Filters whether to show the post locked dialog. * Filters whether to show the post locked dialog.
* *
* Returning a falsey value to the filter will short-circuit displaying the dialog. * Returning false from the filter will prevent the dialog from being displayed.
* *
* @since 3.6.0 * @since 3.6.0
* *
* @param bool $display Whether to display the dialog. Default true. * @param bool $display Whether to display the dialog. Default true.
* @param WP_Post $post Post object. * @param WP_Post $post Post object.
* @param WP_User|bool $user WP_User object on success, false otherwise. * @param WP_User $user The user with the lock for the post.
*/ */
if ( ! apply_filters( 'show_post_locked_dialog', true, $post, $user ) ) { if ( ! apply_filters( 'show_post_locked_dialog', true, $post, $user ) ) {
return; return;
@ -1696,14 +1705,14 @@ function _admin_notice_post_locked() {
/** /**
* Filters whether to allow the post lock to be overridden. * Filters whether to allow the post lock to be overridden.
* *
* Returning a falsey value to the filter will disable the ability * Returning false from the filter will disable the ability
* to override the post lock. * to override the post lock.
* *
* @since 3.6.0 * @since 3.6.0
* *
* @param bool $override Whether to allow overriding post locks. Default true. * @param bool $override Whether to allow the post lock to be overridden. Default true.
* @param WP_Post $post Post object. * @param WP_Post $post Post object.
* @param WP_User $user User object. * @param WP_User $user The user with the lock for the post.
*/ */
$override = apply_filters( 'override_post_lock', true, $post, $user ); $override = apply_filters( 'override_post_lock', true, $post, $user );
$tab_last = $override ? '' : ' wp-tab-last'; $tab_last = $override ? '' : ' wp-tab-last';

2
wp-admin/user-new.php
View File

@ -105,7 +105,7 @@ if ( isset( $_REQUEST['action'] ) && 'adduser' == $_REQUEST['action'] ) {
* @since 4.4.0 * @since 4.4.0
* *
* @param int $user_id The invited user's ID. * @param int $user_id The invited user's ID.
* @param array $role The role of invited user. * @param array $role Array containing role information for the invited user.
* @param string $newuser_key The key of the invitation. * @param string $newuser_key The key of the invitation.
*/ */
do_action( 'invite_user', $user_id, $role, $newuser_key ); do_action( 'invite_user', $user_id, $role, $newuser_key );

6
wp-includes/class-wp-block-styles-registry.php
View File

@ -67,7 +67,7 @@ final class WP_Block_Styles_Registry {
* Unregisters a block style. * Unregisters a block style.
* *
* @param string $block_name Block type name including namespace. * @param string $block_name Block type name including namespace.
* @param array $block_style_name Block style name. * @param string $block_style_name Block style name.
* *
* @return boolean True if the block style was unregistered with success and false otherwise. * @return boolean True if the block style was unregistered with success and false otherwise.
*/ */
@ -90,7 +90,7 @@ final class WP_Block_Styles_Registry {
* @since 5.3.0 * @since 5.3.0
* *
* @param string $block_name Block type name including namespace. * @param string $block_name Block type name including namespace.
* @param array $block_style_name Block style name. * @param string $block_style_name Block style name.
* *
* @return array Registered block style properties. * @return array Registered block style properties.
*/ */
@ -135,7 +135,7 @@ final class WP_Block_Styles_Registry {
* @since 5.3.0 * @since 5.3.0
* *
* @param string $block_name Block type name including namespace. * @param string $block_name Block type name including namespace.
* @param array $block_style_name Block style name. * @param string $block_style_name Block style name.
* *
* @return bool True if the block style is registered, false otherwise. * @return bool True if the block style is registered, false otherwise.
*/ */

8
wp-includes/class-wp-image-editor-gd.php
View File

@ -245,7 +245,13 @@ class WP_Image_Editor_GD extends WP_Image_Editor {
* *
* @since 5.3.0 * @since 5.3.0
* *
* @param array $size_data Array of width, height, and whether to crop. * @param array $size_data {
* Array of size data.
*
* @type int $width The maximum width in pixels.
* @type int $height The maximum height in pixels.
* @type bool $crop Whether to crop the image to exact dimensions.
* }
* @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta. * @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta.
*/ */
public function make_subsize( $size_data ) { public function make_subsize( $size_data ) {

8
wp-includes/class-wp-image-editor-imagick.php
View File

@ -453,7 +453,13 @@ class WP_Image_Editor_Imagick extends WP_Image_Editor {
* *
* @since 5.3.0 * @since 5.3.0
* *
* @param array $size_data Array of width, height, and whether to crop. * @param array $size_data {
* Array of size data.
*
* @type int $width The maximum width in pixels.
* @type int $height The maximum height in pixels.
* @type bool $crop Whether to crop the image to exact dimensions.
* }
* @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta. * @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta.
*/ */
public function make_subsize( $size_data ) { public function make_subsize( $size_data ) {

8
wp-includes/functions.php
View File

@ -2857,7 +2857,9 @@ function wp_get_image_mime( $file ) {
* Retrieve list of mime types and file extensions. * Retrieve list of mime types and file extensions.
* *
* @since 3.5.0 * @since 3.5.0
* @since 4.2.0 Support was added for GIMP (xcf) files. * @since 4.2.0 Support was added for GIMP (.xcf) files.
* @since 4.9.2 Support was added for Flac (.flac) files.
* @since 4.9.6 Support was added for AAC (.aac) files.
* *
* @return array Array of mime types keyed by the file extension regex corresponding to those types. * @return array Array of mime types keyed by the file extension regex corresponding to those types.
*/ */
@ -3042,9 +3044,7 @@ function get_allowed_mime_types( $user = null ) {
* *
* @since 2.0.0 * @since 2.0.0
* *
* @param array $t Mime types keyed by the file extension regex corresponding to * @param array $t Mime types keyed by the file extension regex corresponding to those types.
* those types. 'swf' and 'exe' removed from full list. 'htm|html' also
* removed depending on '$user' capabilities.
* @param int|WP_User|null $user User ID, User object or null if not provided (indicates current user). * @param int|WP_User|null $user User ID, User object or null if not provided (indicates current user).
*/ */
return apply_filters( 'upload_mimes', $t, $user ); return apply_filters( 'upload_mimes', $t, $user );

76
wp-includes/media.php
View File

@ -38,10 +38,7 @@ function wp_get_additional_image_sizes() {
* not set. * not set.
* *
* Finally, there is a filter named {@see 'editor_max_image_size'}, that will be * Finally, there is a filter named {@see 'editor_max_image_size'}, that will be
* called on the calculated array for width and height, respectively. The second * called on the calculated array for width and height, respectively.
* parameter will be the value that was in the $size parameter. The returned
* type for the hook is an array with the width as the first element and the
* height as the second element.
* *
* @since 2.5.0 * @since 2.5.0
* *
@ -54,7 +51,12 @@ function wp_get_additional_image_sizes() {
* Default 'medium'. * Default 'medium'.
* @param string $context Optional. Could be 'display' (like in a theme) or 'edit' * @param string $context Optional. Could be 'display' (like in a theme) or 'edit'
* (like inserting into an editor). Default null. * (like inserting into an editor). Default null.
* @return array Width and height of what the result image should resize to. * @return int[] {
* An array of width and height values.
*
* @type int $0 The maximum width in pixels.
* @type int $1 The maximum height in pixels.
* }
*/ */
function image_constrain_size_for_editor( $width, $height, $size = 'medium', $context = null ) { function image_constrain_size_for_editor( $width, $height, $size = 'medium', $context = null ) {
global $content_width; global $content_width;
@ -117,8 +119,12 @@ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $co
* *
* @since 2.5.0 * @since 2.5.0
* *
* @param array $max_image_size An array with the width as the first element, * @param int[] $max_image_size {
* and the height as the second element. * An array of width and height values.
*
* @type int $0 The maximum width in pixels.
* @type int $1 The maximum height in pixels.
* }
* @param string|array $size Size of what the result image should be. * @param string|array $size Size of what the result image should be.
* @param string $context The context the image is being resized for. * @param string $context The context the image is being resized for.
* Possible values are 'display' (like in a theme) * Possible values are 'display' (like in a theme)
@ -417,7 +423,12 @@ function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
* @param int $current_height Current height of the image. * @param int $current_height Current height of the image.
* @param int $max_width Optional. Max width in pixels to constrain to. Default 0. * @param int $max_width Optional. Max width in pixels to constrain to. Default 0.
* @param int $max_height Optional. Max height in pixels to constrain to. Default 0. * @param int $max_height Optional. Max height in pixels to constrain to. Default 0.
* @return array First item is the width, the second item is the height. * @return int[] {
* An array of width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
*/ */
function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) { function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) {
if ( ! $max_width && ! $max_height ) { if ( ! $max_width && ! $max_height ) {
@ -474,7 +485,12 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width =
* *
* @since 4.1.0 * @since 4.1.0
* *
* @param array $dimensions The image width and height. * @param int[] $dimensions {
* An array of width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
* @param int $current_width The current width of the image. * @param int $current_width The current width of the image.
* @param int $current_height The current height of the image. * @param int $current_height The current height of the image.
* @param int $max_width The maximum width permitted. * @param int $max_width The maximum width permitted.
@ -1149,10 +1165,15 @@ function wp_get_attachment_image_srcset( $attachment_id, $size = 'medium', $imag
* *
* @since 4.4.0 * @since 4.4.0
* *
* @param array $size_array Array of width and height values in pixels (in that order). * @param int[] $size_array {
* An array of width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
* @param string $image_src The 'src' of the image. * @param string $image_src The 'src' of the image.
* @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'.
* @param int $attachment_id Optional. The image attachment ID to pass to the filter. Default 0. * @param int $attachment_id Optional. The image attachment ID. Default 0.
* @return string|bool The 'srcset' attribute value. False on error or when only one source exists. * @return string|bool The 'srcset' attribute value. False on error or when only one source exists.
*/ */
function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attachment_id = 0 ) { function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attachment_id = 0 ) {
@ -1162,7 +1183,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
* @since 4.5.0 * @since 4.5.0
* *
* @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'.
* @param array $size_array Array of width and height values in pixels (in that order). * @param int[] $size_array {
* An array of requested width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
* @param string $image_src The 'src' of the image. * @param string $image_src The 'src' of the image.
* @param int $attachment_id The image attachment ID or 0 if not supplied. * @param int $attachment_id The image attachment ID or 0 if not supplied.
*/ */
@ -1231,7 +1257,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
* @since 4.4.0 * @since 4.4.0
* *
* @param int $max_width The maximum image width to be included in the 'srcset'. Default '2048'. * @param int $max_width The maximum image width to be included in the 'srcset'. Default '2048'.
* @param array $size_array Array of width and height values in pixels (in that order). * @param int[] $size_array {
* An array of requested width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
*/ */
$max_srcset_image_width = apply_filters( 'max_srcset_image_width', 2048, $size_array ); $max_srcset_image_width = apply_filters( 'max_srcset_image_width', 2048, $size_array );
@ -1310,7 +1341,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
* pixel density value if paired with an 'x' descriptor. * pixel density value if paired with an 'x' descriptor.
* } * }
* } * }
* @param array $size_array Array of width and height values in pixels (in that order). * @param array $size_array {
* An array of requested width and height values.
*
* @type int $0 The width in pixels.
* @type int $1 The height in pixels.
* }
* @param string $image_src The 'src' of the image. * @param string $image_src The 'src' of the image.
* @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'. * @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'.
* @param int $attachment_id Image attachment ID or 0. * @param int $attachment_id Image attachment ID or 0.
@ -2376,7 +2412,7 @@ function wp_mediaelement_fallback( $url ) {
} }
/** /**
* Returns a filtered list of WP-supported audio formats. * Returns a filtered list of supported audio formats.
* *
* @since 3.6.0 * @since 3.6.0
* *
@ -2624,7 +2660,7 @@ function wp_audio_shortcode( $attr, $content = '' ) {
add_shortcode( 'audio', 'wp_audio_shortcode' ); add_shortcode( 'audio', 'wp_audio_shortcode' );
/** /**
* Returns a filtered list of WP-supported video formats. * Returns a filtered list of supported video formats.
* *
* @since 3.6.0 * @since 3.6.0
* *
@ -4013,7 +4049,7 @@ function get_attached_media( $type, $post = 0 ) {
* *
* @param array $args Post query arguments. * @param array $args Post query arguments.
* @param string $type Mime type of the desired media. * @param string $type Mime type of the desired media.
* @param mixed $post Post ID or object. * @param WP_Post $post Post object.
*/ */
$args = apply_filters( 'get_attached_media_args', $args, $type, $post ); $args = apply_filters( 'get_attached_media_args', $args, $type, $post );
@ -4026,13 +4062,13 @@ function get_attached_media( $type, $post = 0 ) {
* *
* @param array $children Associative array of media attached to the given post. * @param array $children Associative array of media attached to the given post.
* @param string $type Mime type of the media desired. * @param string $type Mime type of the media desired.
* @param mixed $post Post ID or object. * @param WP_Post $post Post object.
*/ */
return (array) apply_filters( 'get_attached_media', $children, $type, $post ); return (array) apply_filters( 'get_attached_media', $children, $type, $post );
} }
/** /**
* Check the content blob for an audio, video, object, embed, or iframe tags. * Check the content HTML for a audio, video, object, embed, or iframe tags.
* *
* @since 3.6.0 * @since 3.6.0
* *
@ -4288,7 +4324,7 @@ function wpview_media_sandbox_styles() {
} }
/** /**
* Registers the personal data exporter for media * Registers the personal data exporter for media.
* *
* @param array $exporters An array of personal data exporters. * @param array $exporters An array of personal data exporters.
* @return array An array of personal data exporters. * @return array An array of personal data exporters.

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '5.4-alpha-46593'; $wp_version = '5.4-alpha-46594';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.