Skip to content

Commit ec57582

Browse files
staylorstaylor
committed
Add missing doc blocks to wp-admin/includes/*.
Fix some egregious uses of tabbing. Some functions can simply return `apply_filters(...)` instead of setting a variable that is immediately returned. See #32444. git-svn-id: https://develop.svn.wordpress.org/trunk@32654 602fd350-edb4-49c9-b593-d223f7449a82
1 parent d55800a commit ec57582

44 files changed

Lines changed: 557 additions & 191 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/wp-admin/credits.php‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
*
1919
* @since 3.2.0
2020
*
21-
* @return array|bool A list of all of the contributors, or false on error.
21+
* @return array|false A list of all of the contributors, or false on error.
2222
*/
2323
function wp_credits() {
2424
global $wp_version;
@@ -55,7 +55,6 @@ function wp_credits() {
5555
* @param string &$display_name The contributor's display name, passed by reference.
5656
* @param string $username The contributor's username.
5757
* @param string $profiles URL to the contributor's WordPress.org profile page.
58-
* @return string A contributor's display name, hyperlinked to a WordPress.org profile page.
5958
*/
6059
function _wp_credits_add_profile_link( &$display_name, $username, $profiles ) {
6160
$display_name = '<a href="' . esc_url( sprintf( $profiles, $username ) ) . '">' . esc_html( $display_name ) . '</a>';
@@ -68,7 +67,6 @@ function _wp_credits_add_profile_link( &$display_name, $username, $profiles ) {
6867
* @since 3.2.0
6968
*
7069
* @param string &$data External library data, passed by reference.
71-
* @return string Link to the external library.
7270
*/
7371
function _wp_credits_build_object_link( &$data ) {
7472
$data = '<a href="' . esc_url( $data[1] ) . '">' . $data[0] . '</a>';

‎src/wp-admin/custom-background.php‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,6 @@ public function admin_load() {
108108
* @since 3.0.0
109109
*/
110110
public function take_action() {
111-
112111
if ( empty($_POST) )
113112
return;
114113

@@ -357,7 +356,6 @@ public function admin_page() {
357356
* @since 3.0.0
358357
*/
359358
public function handle_upload() {
360-
361359
if ( empty($_FILES) )
362360
return;
363361

@@ -434,6 +432,9 @@ public function ajax_background_add() {
434432
*
435433
* @since 3.4.0
436434
* @deprecated 3.5.0
435+
*
436+
* @param array $form_fields
437+
* @return $form_fields
437438
*/
438439
public function attachment_fields_to_edit( $form_fields ) {
439440
return $form_fields;
@@ -443,6 +444,9 @@ public function attachment_fields_to_edit( $form_fields ) {
443444
*
444445
* @since 3.4.0
445446
* @deprecated 3.5.0
447+
*
448+
* @param $tabs
449+
* @return $tabs
446450
*/
447451
public function filter_upload_tabs( $tabs ) {
448452
return $tabs;

‎src/wp-admin/custom-header.php‎

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -317,7 +317,6 @@ public function js_1() {
317317
}
318318
}
319319
?>
320-
321320
<script type="text/javascript">
322321
(function($){
323322
var default_color = '<?php echo $default_color; ?>',
@@ -925,6 +924,9 @@ public function admin_page() {
925924
* Unused since 3.5.0.
926925
*
927926
* @since 3.4.0
927+
*
928+
* @param array $form_fields
929+
* @return $form_fields
928930
*/
929931
public function attachment_fields_to_edit( $form_fields ) {
930932
return $form_fields;
@@ -934,6 +936,9 @@ public function attachment_fields_to_edit( $form_fields ) {
934936
* Unused since 3.5.0.
935937
*
936938
* @since 3.4.0
939+
*
940+
* @param array $tabs
941+
* @return $tabs
937942
*/
938943
public function filter_upload_tabs( $tabs ) {
939944
return $tabs;
@@ -950,6 +955,8 @@ public function filter_upload_tabs( $tabs ) {
950955
* Or an array of arguments: attachment_id, url, width, height. All are required.
951956
*
952957
* @since 3.4.0
958+
*
959+
* @param array|object|string $choice
953960
*/
954961
final public function set_header_image( $choice ) {
955962
if ( is_array( $choice ) || is_object( $choice ) ) {
@@ -1001,7 +1008,7 @@ final public function set_header_image( $choice ) {
10011008
* @since 3.4.0
10021009
*/
10031010
final public function remove_header_image() {
1004-
return $this->set_header_image( 'remove-header' );
1011+
$this->set_header_image( 'remove-header' );
10051012
}
10061013

10071014
/**
@@ -1015,9 +1022,10 @@ final public function reset_header_image() {
10151022
$this->process_default_headers();
10161023
$default = get_theme_support( 'custom-header', 'default-image' );
10171024

1018-
if ( ! $default )
1019-
return $this->remove_header_image();
1020-
1025+
if ( ! $default ) {
1026+
$this->remove_header_image();
1027+
return;
1028+
}
10211029
$default = sprintf( $default, get_template_directory_uri(), get_stylesheet_directory_uri() );
10221030

10231031
$default_data = array();
@@ -1035,6 +1043,7 @@ final public function reset_header_image() {
10351043
/**
10361044
* Calculate width and height based on what the currently selected theme supports.
10371045
*
1046+
* @param array $dimensions
10381047
* @return array dst_height and dst_width of header image.
10391048
*/
10401049
final public function get_header_dimensions( $dimensions ) {
@@ -1084,8 +1093,8 @@ final public function get_header_dimensions( $dimensions ) {
10841093
/**
10851094
* Create an attachment 'object'.
10861095
*
1087-
* @param string $cropped Cropped image URL.
1088-
* @param int $parent_attachment_id Attachment ID of parent image.
1096+
* @param string $cropped Cropped image URL.
1097+
* @param int $parent_attachment_id Attachment ID of parent image.
10891098
*
10901099
* @return array Attachment object.
10911100
*/
@@ -1112,7 +1121,7 @@ final public function create_attachment_object( $cropped, $parent_attachment_id
11121121
/**
11131122
* Insert an attachment and its metadata.
11141123
*
1115-
* @param array $object Attachment object.
1124+
* @param array $object Attachment object.
11161125
* @param string $cropped Cropped image URL.
11171126
*
11181127
* @return int Attachment ID.
@@ -1240,6 +1249,10 @@ public function ajax_header_remove() {
12401249
wp_send_json_success();
12411250
}
12421251

1252+
/**
1253+
*
1254+
* @param WP_Customize_Manager $wp_customize
1255+
*/
12431256
public function customize_set_last_used( $wp_customize ) {
12441257
$data = $wp_customize->get_setting( 'header_image_data' )->post_value();
12451258

@@ -1252,6 +1265,10 @@ public function customize_set_last_used( $wp_customize ) {
12521265
update_post_meta( $attachment_id, $key, time() );
12531266
}
12541267

1268+
/**
1269+
*
1270+
* @return array
1271+
*/
12551272
public function get_default_header_images() {
12561273
$this->process_default_headers();
12571274

@@ -1285,10 +1302,13 @@ public function get_default_header_images() {
12851302
);
12861303

12871304
// The rest of the set comes after.
1288-
$header_images = array_merge( $header_images, $this->default_headers );
1289-
return $header_images;
1305+
return array_merge( $header_images, $this->default_headers );
12901306
}
12911307

1308+
/**
1309+
*
1310+
* @return array
1311+
*/
12921312
public function get_uploaded_header_images() {
12931313
$header_images = get_uploaded_header_images();
12941314
$timestamp_key = '_wp_attachment_custom_header_last_used_' . get_stylesheet();

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ function get_default_link_to_edit() {
7777
* @global wpdb $wpdb
7878
*
7979
* @param int $link_id ID of the link to delete
80-
* @return bool True
80+
* @return true
8181
*/
8282
function wp_delete_link( $link_id ) {
8383
global $wpdb;
@@ -140,7 +140,7 @@ function get_link_to_edit( $link_id ) {
140140
* @global wpdb $wpdb
141141
*
142142
* @param array $linkdata Elements that make up the link to insert.
143-
* @param bool $wp_error Optional. If true return WP_Error object on failure.
143+
* @param bool $wp_error Optional. If true return WP_Error object on failure.
144144
* @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success.
145145
*/
146146
function wp_insert_link( $linkdata, $wp_error = false ) {

‎src/wp-admin/includes/class-wp-comments-list-table.php‎

Lines changed: 51 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@ public function __construct( $args = array() ) {
5353
) );
5454
}
5555

56+
/**
57+
* @return bool
58+
*/
5659
public function ajax_user_can() {
5760
return current_user_can('edit_posts');
5861
}
@@ -158,8 +161,7 @@ public function get_per_page( $comment_status = 'all' ) {
158161
* @param int $comments_per_page The number of comments to list per page.
159162
* @param string $comment_status The comment status name. Default 'All'.
160163
*/
161-
$comments_per_page = apply_filters( 'comments_per_page', $comments_per_page, $comment_status );
162-
return $comments_per_page;
164+
return apply_filters( 'comments_per_page', $comments_per_page, $comment_status );
163165
}
164166

165167
/**
@@ -230,13 +232,14 @@ protected function get_views() {
230232
* @param array $status_links An array of fully-formed status links. Default 'All'.
231233
* Accepts 'All', 'Pending', 'Approved', 'Spam', and 'Trash'.
232234
*/
233-
$status_links = apply_filters( 'comment_status_links', $status_links );
234-
return $status_links;
235+
return apply_filters( 'comment_status_links', $status_links );
235236
}
236237

237238
/**
238239
*
239240
* @global string $comment_status
241+
*
242+
* @return array
240243
*/
241244
protected function get_bulk_actions() {
242245
global $comment_status;
@@ -266,6 +269,7 @@ protected function get_bulk_actions() {
266269
*
267270
* @global string $comment_status
268271
* @global string $comment_type
272+
*
269273
* @param string $which
270274
*/
271275
protected function extra_tablenav( $which ) {
@@ -321,6 +325,9 @@ protected function extra_tablenav( $which ) {
321325
echo '</div>';
322326
}
323327

328+
/**
329+
* @return string|false
330+
*/
324331
public function current_action() {
325332
if ( isset( $_REQUEST['delete_all'] ) || isset( $_REQUEST['delete_all2'] ) )
326333
return 'delete_all';
@@ -331,6 +338,7 @@ public function current_action() {
331338
/**
332339
*
333340
* @global int $post_id
341+
*
334342
* @return array
335343
*/
336344
public function get_columns() {
@@ -350,6 +358,10 @@ public function get_columns() {
350358
return $columns;
351359
}
352360

361+
/**
362+
*
363+
* @return array
364+
*/
353365
protected function get_sortable_columns() {
354366
return array(
355367
'author' => 'comment_author',
@@ -406,6 +418,7 @@ public function display() {
406418
*
407419
* @global WP_Post $post
408420
* @global object $comment
421+
*
409422
* @param object $a_comment
410423
*/
411424
public function single_row( $a_comment ) {
@@ -437,14 +450,13 @@ public function single_row( $a_comment ) {
437450
* @param string $column_name Current column name
438451
* @param string $primary Primary column name
439452
*
440-
* @return string
453+
* @return string|void
441454
*/
442455
protected function handle_row_actions( $comment, $column_name, $primary ) {
443456
global $comment_status;
444-
457+
445458
if ( ! $this->user_can ) {
446459
return;
447-
448460
}
449461

450462
$post = get_post();
@@ -542,6 +554,10 @@ protected function handle_row_actions( $comment, $column_name, $primary ) {
542554
return $out;
543555
}
544556

557+
/**
558+
*
559+
* @param object $comment
560+
*/
545561
public function column_cb( $comment ) {
546562
if ( $this->user_can ) { ?>
547563
<label class="screen-reader-text" for="cb-select-<?php echo $comment->comment_ID; ?>"><?php _e( 'Select comment' ); ?></label>
@@ -553,6 +569,7 @@ public function column_cb( $comment ) {
553569
/**
554570
*
555571
* @global string $comment_status
572+
*
556573
* @param object $comment
557574
*/
558575
public function column_comment( $comment ) {
@@ -601,6 +618,7 @@ public function column_comment( $comment ) {
601618
/**
602619
*
603620
* @global string $comment_status
621+
*
604622
* @param object $comment
605623
*/
606624
public function column_author( $comment ) {
@@ -634,6 +652,10 @@ public function column_author( $comment ) {
634652
}
635653
}
636654

655+
/**
656+
*
657+
* @return string
658+
*/
637659
public function column_date() {
638660
return get_comment_date( __( 'Y/m/d \a\t g:i a' ) );
639661
}
@@ -666,6 +688,11 @@ public function column_response() {
666688
echo $thumb;
667689
}
668690

691+
/**
692+
*
693+
* @param object $comment
694+
* @param string $column_name
695+
*/
669696
public function column_default( $comment, $column_name ) {
670697
/**
671698
* Fires when the default column output is displayed for a single row.
@@ -691,6 +718,10 @@ public function column_default( $comment, $column_name ) {
691718
*/
692719
class WP_Post_Comments_List_Table extends WP_Comments_List_Table {
693720

721+
/**
722+
*
723+
* @return array
724+
*/
694725
protected function get_column_info() {
695726
return array(
696727
array(
@@ -703,12 +734,20 @@ protected function get_column_info() {
703734
);
704735
}
705736

737+
/**
738+
*
739+
* @return array
740+
*/
706741
protected function get_table_classes() {
707742
$classes = parent::get_table_classes();
708743
$classes[] = 'comments-box';
709744
return $classes;
710745
}
711746

747+
/**
748+
*
749+
* @param bool $output_empty
750+
*/
712751
public function display( $output_empty = false ) {
713752
$singular = $this->_args['singular'];
714753

@@ -727,6 +766,11 @@ public function display( $output_empty = false ) {
727766
<?php
728767
}
729768

769+
/**
770+
*
771+
* @param bool $comment_status
772+
* @return int
773+
*/
730774
public function get_per_page( $comment_status = false ) {
731775
return 10;
732776
}

0 commit comments

Comments
 (0)