Skip to content

Commit a2e0803

Browse files
johnbillionjohnbillion
committed
Docs: Miscellaneous docblock fixes and improvements.
See #48303 git-svn-id: https://develop.svn.wordpress.org/trunk@46594 602fd350-edb4-49c9-b593-d223f7449a82
1 parent c951d94 commit a2e0803

7 files changed

Lines changed: 101 additions & 44 deletions

File tree

‎src/wp-admin/includes/post.php‎

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1319,7 +1319,12 @@ function postbox_classes( $box_id, $screen_id ) {
13191319
* @param int $id Post ID or post object.
13201320
* @param string $title Optional. Title to override the post's current title when generating the post name. Default null.
13211321
* @param string $name Optional. Name to override the post name. Default null.
1322-
* @return array Array containing the sample permalink with placeholder for the post name, and the post name.
1322+
* @return array {
1323+
* Array containing the sample permalink with placeholder for the post name, and the post name.
1324+
*
1325+
* @type string $0 The permalink with placeholder for the post name.
1326+
* @type string $1 The post name.
1327+
* }
13231328
*/
13241329
function get_sample_permalink( $id, $title = null, $name = null ) {
13251330
$post = get_post( $id );
@@ -1383,7 +1388,12 @@ function get_sample_permalink( $id, $title = null, $name = null ) {
13831388
*
13841389
* @since 4.4.0
13851390
*
1386-
* @param array $permalink Array containing the sample permalink with placeholder for the post name, and the post name.
1391+
* @param array $permalink {
1392+
* Array containing the sample permalink with placeholder for the post name, and the post name.
1393+
*
1394+
* @type string $0 The permalink with placeholder for the post name.
1395+
* @type string $1 The post name.
1396+
* }
13871397
* @param int $post_id Post ID.
13881398
* @param string $title Post title.
13891399
* @param string $name Post name (slug).
@@ -1637,17 +1647,16 @@ function _admin_notice_post_locked() {
16371647
}
16381648

16391649
if ( $user ) {
1640-
16411650
/**
16421651
* Filters whether to show the post locked dialog.
16431652
*
1644-
* Returning a falsey value to the filter will short-circuit displaying the dialog.
1653+
* Returning false from the filter will prevent the dialog from being displayed.
16451654
*
16461655
* @since 3.6.0
16471656
*
1648-
* @param bool $display Whether to display the dialog. Default true.
1649-
* @param WP_Post $post Post object.
1650-
* @param WP_User|bool $user WP_User object on success, false otherwise.
1657+
* @param bool $display Whether to display the dialog. Default true.
1658+
* @param WP_Post $post Post object.
1659+
* @param WP_User $user The user with the lock for the post.
16511660
*/
16521661
if ( ! apply_filters( 'show_post_locked_dialog', true, $post, $user ) ) {
16531662
return;
@@ -1696,14 +1705,14 @@ function _admin_notice_post_locked() {
16961705
/**
16971706
* Filters whether to allow the post lock to be overridden.
16981707
*
1699-
* Returning a falsey value to the filter will disable the ability
1708+
* Returning false from the filter will disable the ability
17001709
* to override the post lock.
17011710
*
17021711
* @since 3.6.0
17031712
*
1704-
* @param bool $override Whether to allow overriding post locks. Default true.
1713+
* @param bool $override Whether to allow the post lock to be overridden. Default true.
17051714
* @param WP_Post $post Post object.
1706-
* @param WP_User $user User object.
1715+
* @param WP_User $user The user with the lock for the post.
17071716
*/
17081717
$override = apply_filters( 'override_post_lock', true, $post, $user );
17091718
$tab_last = $override ? '' : ' wp-tab-last';

‎src/wp-admin/user-new.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@
105105
* @since 4.4.0
106106
*
107107
* @param int $user_id The invited user's ID.
108-
* @param array $role The role of invited user.
108+
* @param array $role Array containing role information for the invited user.
109109
* @param string $newuser_key The key of the invitation.
110110
*/
111111
do_action( 'invite_user', $user_id, $role, $newuser_key );

‎src/wp-includes/class-wp-block-styles-registry.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ public function register( $block_name, $style_properties ) {
6767
* Unregisters a block style.
6868
*
6969
* @param string $block_name Block type name including namespace.
70-
* @param array $block_style_name Block style name.
70+
* @param string $block_style_name Block style name.
7171
*
7272
* @return boolean True if the block style was unregistered with success and false otherwise.
7373
*/
@@ -90,7 +90,7 @@ public function unregister( $block_name, $block_style_name ) {
9090
* @since 5.3.0
9191
*
9292
* @param string $block_name Block type name including namespace.
93-
* @param array $block_style_name Block style name.
93+
* @param string $block_style_name Block style name.
9494
*
9595
* @return array Registered block style properties.
9696
*/
@@ -135,7 +135,7 @@ public function get_registered_styles_for_block( $block_name ) {
135135
* @since 5.3.0
136136
*
137137
* @param string $block_name Block type name including namespace.
138-
* @param array $block_style_name Block style name.
138+
* @param string $block_style_name Block style name.
139139
*
140140
* @return bool True if the block style is registered, false otherwise.
141141
*/

‎src/wp-includes/class-wp-image-editor-gd.php‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,13 @@ public function multi_resize( $sizes ) {
245245
*
246246
* @since 5.3.0
247247
*
248-
* @param array $size_data Array of width, height, and whether to crop.
248+
* @param array $size_data {
249+
* Array of size data.
250+
*
251+
* @type int $width The maximum width in pixels.
252+
* @type int $height The maximum height in pixels.
253+
* @type bool $crop Whether to crop the image to exact dimensions.
254+
* }
249255
* @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta.
250256
*/
251257
public function make_subsize( $size_data ) {

‎src/wp-includes/class-wp-image-editor-imagick.php‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -453,7 +453,13 @@ public function multi_resize( $sizes ) {
453453
*
454454
* @since 5.3.0
455455
*
456-
* @param array $size_data Array of width, height, and whether to crop.
456+
* @param array $size_data {
457+
* Array of size data.
458+
*
459+
* @type int $width The maximum width in pixels.
460+
* @type int $height The maximum height in pixels.
461+
* @type bool $crop Whether to crop the image to exact dimensions.
462+
* }
457463
* @return WP_Error|array WP_Error on error, or the image data array for inclusion in the `sizes` array in the image meta.
458464
*/
459465
public function make_subsize( $size_data ) {

‎src/wp-includes/functions.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2857,7 +2857,9 @@ function wp_get_image_mime( $file ) {
28572857
* Retrieve list of mime types and file extensions.
28582858
*
28592859
* @since 3.5.0
2860-
* @since 4.2.0 Support was added for GIMP (xcf) files.
2860+
* @since 4.2.0 Support was added for GIMP (.xcf) files.
2861+
* @since 4.9.2 Support was added for Flac (.flac) files.
2862+
* @since 4.9.6 Support was added for AAC (.aac) files.
28612863
*
28622864
* @return array Array of mime types keyed by the file extension regex corresponding to those types.
28632865
*/
@@ -3042,9 +3044,7 @@ function get_allowed_mime_types( $user = null ) {
30423044
*
30433045
* @since 2.0.0
30443046
*
3045-
* @param array $t Mime types keyed by the file extension regex corresponding to
3046-
* those types. 'swf' and 'exe' removed from full list. 'htm|html' also
3047-
* removed depending on '$user' capabilities.
3047+
* @param array $t Mime types keyed by the file extension regex corresponding to those types.
30483048
* @param int|WP_User|null $user User ID, User object or null if not provided (indicates current user).
30493049
*/
30503050
return apply_filters( 'upload_mimes', $t, $user );

‎src/wp-includes/media.php‎

Lines changed: 60 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,7 @@ function wp_get_additional_image_sizes() {
3838
* not set.
3939
*
4040
* Finally, there is a filter named {@see 'editor_max_image_size'}, that will be
41-
* called on the calculated array for width and height, respectively. The second
42-
* parameter will be the value that was in the $size parameter. The returned
43-
* type for the hook is an array with the width as the first element and the
44-
* height as the second element.
41+
* called on the calculated array for width and height, respectively.
4542
*
4643
* @since 2.5.0
4744
*
@@ -54,7 +51,12 @@ function wp_get_additional_image_sizes() {
5451
* Default 'medium'.
5552
* @param string $context Optional. Could be 'display' (like in a theme) or 'edit'
5653
* (like inserting into an editor). Default null.
57-
* @return array Width and height of what the result image should resize to.
54+
* @return int[] {
55+
* An array of width and height values.
56+
*
57+
* @type int $0 The maximum width in pixels.
58+
* @type int $1 The maximum height in pixels.
59+
* }
5860
*/
5961
function image_constrain_size_for_editor( $width, $height, $size = 'medium', $context = null ) {
6062
global $content_width;
@@ -117,8 +119,12 @@ function image_constrain_size_for_editor( $width, $height, $size = 'medium', $co
117119
*
118120
* @since 2.5.0
119121
*
120-
* @param array $max_image_size An array with the width as the first element,
121-
* and the height as the second element.
122+
* @param int[] $max_image_size {
123+
* An array of width and height values.
124+
*
125+
* @type int $0 The maximum width in pixels.
126+
* @type int $1 The maximum height in pixels.
127+
* }
122128
* @param string|array $size Size of what the result image should be.
123129
* @param string $context The context the image is being resized for.
124130
* Possible values are 'display' (like in a theme)
@@ -417,7 +423,12 @@ function get_image_tag( $id, $alt, $title, $align, $size = 'medium' ) {
417423
* @param int $current_height Current height of the image.
418424
* @param int $max_width Optional. Max width in pixels to constrain to. Default 0.
419425
* @param int $max_height Optional. Max height in pixels to constrain to. Default 0.
420-
* @return array First item is the width, the second item is the height.
426+
* @return int[] {
427+
* An array of width and height values.
428+
*
429+
* @type int $0 The width in pixels.
430+
* @type int $1 The height in pixels.
431+
* }
421432
*/
422433
function wp_constrain_dimensions( $current_width, $current_height, $max_width = 0, $max_height = 0 ) {
423434
if ( ! $max_width && ! $max_height ) {
@@ -474,7 +485,12 @@ function wp_constrain_dimensions( $current_width, $current_height, $max_width =
474485
*
475486
* @since 4.1.0
476487
*
477-
* @param array $dimensions The image width and height.
488+
* @param int[] $dimensions {
489+
* An array of width and height values.
490+
*
491+
* @type int $0 The width in pixels.
492+
* @type int $1 The height in pixels.
493+
* }
478494
* @param int $current_width The current width of the image.
479495
* @param int $current_height The current height of the image.
480496
* @param int $max_width The maximum width permitted.
@@ -1149,10 +1165,15 @@ function wp_get_attachment_image_srcset( $attachment_id, $size = 'medium', $imag
11491165
*
11501166
* @since 4.4.0
11511167
*
1152-
* @param array $size_array Array of width and height values in pixels (in that order).
1168+
* @param int[] $size_array {
1169+
* An array of width and height values.
1170+
*
1171+
* @type int $0 The width in pixels.
1172+
* @type int $1 The height in pixels.
1173+
* }
11531174
* @param string $image_src The 'src' of the image.
11541175
* @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'.
1155-
* @param int $attachment_id Optional. The image attachment ID to pass to the filter. Default 0.
1176+
* @param int $attachment_id Optional. The image attachment ID. Default 0.
11561177
* @return string|bool The 'srcset' attribute value. False on error or when only one source exists.
11571178
*/
11581179
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
11621183
* @since 4.5.0
11631184
*
11641185
* @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'.
1165-
* @param array $size_array Array of width and height values in pixels (in that order).
1186+
* @param int[] $size_array {
1187+
* An array of requested width and height values.
1188+
*
1189+
* @type int $0 The width in pixels.
1190+
* @type int $1 The height in pixels.
1191+
* }
11661192
* @param string $image_src The 'src' of the image.
11671193
* @param int $attachment_id The image attachment ID or 0 if not supplied.
11681194
*/
@@ -1231,7 +1257,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
12311257
* @since 4.4.0
12321258
*
12331259
* @param int $max_width The maximum image width to be included in the 'srcset'. Default '2048'.
1234-
* @param array $size_array Array of width and height values in pixels (in that order).
1260+
* @param int[] $size_array {
1261+
* An array of requested width and height values.
1262+
*
1263+
* @type int $0 The width in pixels.
1264+
* @type int $1 The height in pixels.
1265+
* }
12351266
*/
12361267
$max_srcset_image_width = apply_filters( 'max_srcset_image_width', 2048, $size_array );
12371268

@@ -1310,7 +1341,12 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
13101341
* pixel density value if paired with an 'x' descriptor.
13111342
* }
13121343
* }
1313-
* @param array $size_array Array of width and height values in pixels (in that order).
1344+
* @param array $size_array {
1345+
* An array of requested width and height values.
1346+
*
1347+
* @type int $0 The width in pixels.
1348+
* @type int $1 The height in pixels.
1349+
* }
13141350
* @param string $image_src The 'src' of the image.
13151351
* @param array $image_meta The image meta data as returned by 'wp_get_attachment_metadata()'.
13161352
* @param int $attachment_id Image attachment ID or 0.
@@ -2376,7 +2412,7 @@ function wp_mediaelement_fallback( $url ) {
23762412
}
23772413

23782414
/**
2379-
* Returns a filtered list of WP-supported audio formats.
2415+
* Returns a filtered list of supported audio formats.
23802416
*
23812417
* @since 3.6.0
23822418
*
@@ -2624,7 +2660,7 @@ function wp_audio_shortcode( $attr, $content = '' ) {
26242660
add_shortcode( 'audio', 'wp_audio_shortcode' );
26252661

26262662
/**
2627-
* Returns a filtered list of WP-supported video formats.
2663+
* Returns a filtered list of supported video formats.
26282664
*
26292665
* @since 3.6.0
26302666
*
@@ -4011,9 +4047,9 @@ function get_attached_media( $type, $post = 0 ) {
40114047
*
40124048
* @since 3.6.0
40134049
*
4014-
* @param array $args Post query arguments.
4015-
* @param string $type Mime type of the desired media.
4016-
* @param mixed $post Post ID or object.
4050+
* @param array $args Post query arguments.
4051+
* @param string $type Mime type of the desired media.
4052+
* @param WP_Post $post Post object.
40174053
*/
40184054
$args = apply_filters( 'get_attached_media_args', $args, $type, $post );
40194055

@@ -4024,15 +4060,15 @@ function get_attached_media( $type, $post = 0 ) {
40244060
*
40254061
* @since 3.6.0
40264062
*
4027-
* @param array $children Associative array of media attached to the given post.
4028-
* @param string $type Mime type of the media desired.
4029-
* @param mixed $post Post ID or object.
4063+
* @param array $children Associative array of media attached to the given post.
4064+
* @param string $type Mime type of the media desired.
4065+
* @param WP_Post $post Post object.
40304066
*/
40314067
return (array) apply_filters( 'get_attached_media', $children, $type, $post );
40324068
}
40334069

40344070
/**
4035-
* Check the content blob for an audio, video, object, embed, or iframe tags.
4071+
* Check the content HTML for a audio, video, object, embed, or iframe tags.
40364072
*
40374073
* @since 3.6.0
40384074
*
@@ -4288,7 +4324,7 @@ function wpview_media_sandbox_styles() {
42884324
}
42894325

42904326
/**
4291-
* Registers the personal data exporter for media
4327+
* Registers the personal data exporter for media.
42924328
*
42934329
* @param array $exporters An array of personal data exporters.
42944330
* @return array An array of personal data exporters.

0 commit comments

Comments
 (0)