Skip to content

Commit db4f746

Browse files
johnbillionjohnbillion
committed
Docs: Improve documentation of known return types, plus other docs fixes.
See #48303 git-svn-id: https://develop.svn.wordpress.org/trunk@46660 602fd350-edb4-49c9-b593-d223f7449a82
1 parent 63d4dcd commit db4f746

31 files changed

Lines changed: 177 additions & 119 deletions

‎src/wp-includes/comment-template.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -452,7 +452,7 @@ function comment_class( $class = '', $comment = null, $post_id = null, $echo = t
452452
* @param string|array $class Optional. One or more classes to add to the class list. Default empty.
453453
* @param int|WP_Comment $comment_id Comment ID or WP_Comment object. Default current comment.
454454
* @param int|WP_Post $post_id Post ID or WP_Post object. Default current post.
455-
* @return array An array of classes.
455+
* @return string[] An array of classes.
456456
*/
457457
function get_comment_class( $class = '', $comment_id = null, $post_id = null ) {
458458
global $comment_alt, $comment_depth, $comment_thread_alt;

‎src/wp-includes/comment.php‎

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,7 @@ function get_comments( $args = '' ) {
251251
*
252252
* @since 2.7.0
253253
*
254-
* @return array List of comment statuses.
254+
* @return string[] List of comment status labels keyed by status.
255255
*/
256256
function get_comment_statuses() {
257257
$status = array(
@@ -1163,7 +1163,7 @@ function get_page_of_comment( $comment_ID, $args = array() ) {
11631163
*
11641164
* @global wpdb $wpdb WordPress database abstraction object.
11651165
*
1166-
* @return array Maximum character length for the comment form fields.
1166+
* @return int[] Array of maximum lengths keyed by field name.
11671167
*/
11681168
function wp_get_comment_fields_max_lengths() {
11691169
global $wpdb;
@@ -1206,7 +1206,7 @@ function wp_get_comment_fields_max_lengths() {
12061206
*
12071207
* @since 4.5.0
12081208
*
1209-
* @param array $lengths Associative array `'field_name' => 'maximum length'`.
1209+
* @param int[] $lengths Array of maximum lengths keyed by field name.
12101210
*/
12111211
return apply_filters( 'wp_get_comment_fields_max_lengths', $lengths );
12121212
}
@@ -1778,7 +1778,13 @@ function _clear_modified_cache_on_transition_comment_status( $new_status, $old_s
17781778
*
17791779
* @since 2.0.4
17801780
*
1781-
* @return array Comment author, email, url respectively.
1781+
* @return array {
1782+
* An array of current commenter variables.
1783+
*
1784+
* @type string $comment_author The name of the current commenter, or an empty string.
1785+
* @type string $comment_author_email The email address of the current commenter, or an empty string.
1786+
* @type string $comment_author_url The URL address of the current commenter, or an empty string.
1787+
* }
17821788
*/
17831789
function wp_get_current_commenter() {
17841790
// Cookies should already be sanitized.
@@ -1806,9 +1812,9 @@ function wp_get_current_commenter() {
18061812
* @param array $comment_author_data {
18071813
* An array of current commenter variables.
18081814
*
1809-
* @type string $comment_author The name of the author of the comment. Default empty.
1810-
* @type string $comment_author_email The email address of the `$comment_author`. Default empty.
1811-
* @type string $comment_author_url The URL address of the `$comment_author`. Default empty.
1815+
* @type string $comment_author The name of the current commenter, or an empty string.
1816+
* @type string $comment_author_email The email address of the current commenter, or an empty string.
1817+
* @type string $comment_author_url The URL address of the current commenter, or an empty string.
18121818
* }
18131819
*/
18141820
return apply_filters( 'wp_get_current_commenter', compact( 'comment_author', 'comment_author_email', 'comment_author_url' ) );

‎src/wp-includes/customize/class-wp-customize-media-control.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -207,7 +207,7 @@ public function content_template() {
207207
*
208208
* @since 4.9.0
209209
*
210-
* @return array An associative array of default button labels.
210+
* @return string[] An associative array of default button labels keyed by the button name.
211211
*/
212212
public function get_default_button_labels() {
213213
// Get just the mime type and strip the mime subtype if present.

‎src/wp-includes/customize/class-wp-customize-nav-menu-setting.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -381,7 +381,7 @@ public function filter_wp_get_nav_menu_object( $menu_obj, $menu_id ) {
381381
* @since 4.3.0
382382
*
383383
* @param array $nav_menu_options Nav menu options including auto_add.
384-
* @return array (Kaybe) modified nav menu options.
384+
* @return array (Maybe) modified nav menu options.
385385
*/
386386
public function filter_nav_menu_options( $nav_menu_options ) {
387387
if ( $this->_previewed_blog_id !== get_current_blog_id() ) {

‎src/wp-includes/embed.php‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,12 @@ function wp_embed_unregister_handler( $id, $priority = 10 ) {
5858
*
5959
* @param string $url Optional. The URL that should be embedded. Default empty.
6060
*
61-
* @return array Default embed parameters.
61+
* @return array {
62+
* Indexed array of the embed width and height in pixels.
63+
*
64+
* @type int $0 The embed width.
65+
* @type int $1 The embed height.
66+
* }
6267
*/
6368
function wp_embed_defaults( $url = '' ) {
6469
if ( ! empty( $GLOBALS['content_width'] ) ) {

‎src/wp-includes/formatting.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -622,7 +622,7 @@ function wpautop( $pee, $br = true ) {
622622
* @since 4.2.4
623623
*
624624
* @param string $input The text which has to be formatted.
625-
* @return array The formatted text.
625+
* @return string[] Array of the formatted text.
626626
*/
627627
function wp_html_split( $input ) {
628628
return preg_split( get_html_split_regex(), $input, -1, PREG_SPLIT_DELIM_CAPTURE );

‎src/wp-includes/functions.php‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -766,7 +766,7 @@ function xmlrpc_removepostdata( $content ) {
766766
* @since 3.7.0
767767
*
768768
* @param string $content Content to extract URLs from.
769-
* @return array URLs found in passed string.
769+
* @return string[] Array of URLs found in passed string.
770770
*/
771771
function wp_extract_urls( $content ) {
772772
preg_match_all(
@@ -2487,7 +2487,7 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null )
24872487
*
24882488
* @param string $name Filename.
24892489
* @param null|string $deprecated Never used. Set to null.
2490-
* @param mixed $bits File content
2490+
* @param string $bits File content
24912491
* @param string $time Optional. Time formatted in 'yyyy/mm'. Default null.
24922492
* @return array
24932493
*/
@@ -3003,7 +3003,7 @@ function wp_get_mime_types() {
30033003
*
30043004
* @since 4.6.0
30053005
*
3006-
* @return array Array of file extensions types keyed by the type of file.
3006+
* @return array[] Multi-dimensional array of file extensions types keyed by the type of file.
30073007
*/
30083008
function wp_get_ext_types() {
30093009

@@ -3014,8 +3014,7 @@ function wp_get_ext_types() {
30143014
*
30153015
* @see wp_ext2type()
30163016
*
3017-
* @param array $ext2type Multi-dimensional array with extensions for a default set
3018-
* of file types.
3017+
* @param array[] $ext2type Multi-dimensional array of file extensions types keyed by the type of file.
30193018
*/
30203019
return apply_filters(
30213020
'ext2type',
@@ -4262,7 +4261,7 @@ function wp_parse_list( $list ) {
42624261
* @since 3.0.0
42634262
*
42644263
* @param array|string $list List of ids.
4265-
* @return array Sanitized array of IDs.
4264+
* @return int[] Sanitized array of IDs.
42664265
*/
42674266
function wp_parse_id_list( $list ) {
42684267
$list = wp_parse_list( $list );
@@ -4276,7 +4275,7 @@ function wp_parse_id_list( $list ) {
42764275
* @since 4.7.0
42774276
*
42784277
* @param array|string $list List of slugs.
4279-
* @return array Sanitized array of slugs.
4278+
* @return string[] Sanitized array of slugs.
42804279
*/
42814280
function wp_parse_slug_list( $list ) {
42824281
$list = wp_parse_list( $list );
@@ -5842,7 +5841,7 @@ function wp_scheduled_delete() {
58425841
* @param array $default_headers List of headers, in the format `array( 'HeaderKey' => 'Header Name' )`.
58435842
* @param string $context Optional. If specified adds filter hook {@see 'extra_$context_headers'}.
58445843
* Default empty.
5845-
* @return array Array of file headers in `HeaderKey => Header Value` format.
5844+
* @return string[] Array of file header values keyed by header name.
58465845
*/
58475846
function get_file_data( $file, $default_headers, $context = '' ) {
58485847
// We don't need to write to the file, so just open for reading.

‎src/wp-includes/functions.wp-scripts.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ function _wp_scripts_maybe_doing_it_wrong( $function ) {
6565
* @since 2.1.0
6666
*
6767
* @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'.
68-
* @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
68+
* @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array.
6969
*/
7070
function wp_print_scripts( $handles = false ) {
7171
/**

‎src/wp-includes/functions.wp-styles.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ function wp_styles() {
3737
* @since 2.6.0
3838
*
3939
* @param string|bool|array $handles Styles to be printed. Default 'false'.
40-
* @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
40+
* @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array.
4141
*/
4242
function wp_print_styles( $handles = false ) {
4343
if ( '' === $handles ) { // for wp_head

‎src/wp-includes/general-template.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3286,7 +3286,7 @@ function wp_resource_hints() {
32863286
*
32873287
* @since 4.6.0
32883288
*
3289-
* @return array A list of unique hosts of enqueued scripts and styles.
3289+
* @return string[] A list of unique hosts of enqueued scripts and styles.
32903290
*/
32913291
function wp_dependencies_unique_hosts() {
32923292
global $wp_scripts, $wp_styles;

0 commit comments

Comments
 (0)