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.

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


git-svn-id: http://core.svn.wordpress.org/trunk@32624 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/credits.php

@@ -18,7 +18,7 @@ $title = __( 'Credits' );
  *
  * @since 3.2.0
  *
- * @return array|bool A list of all of the contributors, or false on error.
+ * @return array|false A list of all of the contributors, or false on error.
 */
 function wp_credits() {
 	global $wp_version;
@@ -55,7 +55,6 @@ function wp_credits() {
  * @param string &$display_name The contributor's display name, passed by reference.
  * @param string $username      The contributor's username.
  * @param string $profiles      URL to the contributor's WordPress.org profile page.
- * @return string A contributor's display name, hyperlinked to a WordPress.org profile page.
  */
 function _wp_credits_add_profile_link( &$display_name, $username, $profiles ) {
 	$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 ) {
  * @since 3.2.0
  *
  * @param string &$data External library data, passed by reference.
- * @return string Link to the external library.
  */
 function _wp_credits_build_object_link( &$data ) {
 	$data = '<a href="' . esc_url( $data[1] ) . '">' . $data[0] . '</a>';

wp-admin/custom-background.php

@@ -108,7 +108,6 @@ class Custom_Background {
 	 * @since 3.0.0
 	 */
 	public function take_action() {
-
 		if ( empty($_POST) )
 			return;
 
@@ -357,7 +356,6 @@ if ( current_theme_supports( 'custom-background', 'default-color' ) )
 	 * @since 3.0.0
 	 */
 	public function handle_upload() {
-
 		if ( empty($_FILES) )
 			return;
 
@@ -434,6 +432,9 @@ if ( current_theme_supports( 'custom-background', 'default-color' ) )
 	 *
 	 * @since 3.4.0
 	 * @deprecated 3.5.0
+	 *
+	 * @param array $form_fields
+	 * @return $form_fields
 	 */
 	public function attachment_fields_to_edit( $form_fields ) {
 		return $form_fields;
@@ -443,6 +444,9 @@ if ( current_theme_supports( 'custom-background', 'default-color' ) )
 	 *
 	 * @since 3.4.0
 	 * @deprecated 3.5.0
+	 *
+	 * @param $tabs
+	 * @return $tabs
 	 */
 	public function filter_upload_tabs( $tabs ) {
 		return $tabs;

wp-admin/custom-header.php

@@ -317,7 +317,6 @@ class Custom_Image_Header {
 			}
 		}
 		?>
-
 <script type="text/javascript">
 (function($){
 	var default_color = '<?php echo $default_color; ?>',
@@ -925,6 +924,9 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	 * Unused since 3.5.0.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param array $form_fields
+	 * @return $form_fields
 	 */
 	public function attachment_fields_to_edit( $form_fields ) {
 		return $form_fields;
@@ -934,6 +936,9 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	 * Unused since 3.5.0.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param array $tabs
+	 * @return $tabs
 	 */
 	public function filter_upload_tabs( $tabs ) {
 		return $tabs;
@@ -950,6 +955,8 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	 *  Or an array of arguments: attachment_id, url, width, height. All are required.
 	 *
 	 * @since 3.4.0
+	 *
+	 * @param array|object|string $choice
 	 */
 	final public function set_header_image( $choice ) {
 		if ( is_array( $choice ) || is_object( $choice ) ) {
@@ -1001,7 +1008,7 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	 * @since 3.4.0
 	 */
 	final public function remove_header_image() {
-		return $this->set_header_image( 'remove-header' );
+		$this->set_header_image( 'remove-header' );
 	}
 
 	/**
@@ -1015,9 +1022,10 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 		$this->process_default_headers();
 		$default = get_theme_support( 'custom-header', 'default-image' );
 
-		if ( ! $default )
+		if ( ! $default ) {
-			return $this->remove_header_image();
+			$this->remove_header_image();
-
+			return;
+		}
 		$default = sprintf( $default, get_template_directory_uri(), get_stylesheet_directory_uri() );
 
 		$default_data = array();
@@ -1035,6 +1043,7 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Calculate width and height based on what the currently selected theme supports.
 	 *
+	 * @param array $dimensions
 	 * @return array dst_height and dst_width of header image.
 	 */
 	final public function get_header_dimensions( $dimensions ) {
@@ -1084,8 +1093,8 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Create an attachment 'object'.
 	 *
-	 * @param string $cropped Cropped image URL.
+	 * @param string $cropped              Cropped image URL.
-	 * @param int $parent_attachment_id Attachment ID of parent image.
+	 * @param int    $parent_attachment_id Attachment ID of parent image.
 	 *
 	 * @return array Attachment object.
 	 */
@@ -1112,7 +1121,7 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 	/**
 	 * Insert an attachment and its metadata.
 	 *
-	 * @param array $object Attachment object.
+	 * @param array  $object  Attachment object.
 	 * @param string $cropped Cropped image URL.
 	 *
 	 * @return int Attachment ID.
@@ -1240,6 +1249,10 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 		wp_send_json_success();
 	}
 
+	/**
+	 *
+	 * @param WP_Customize_Manager $wp_customize
+	 */
 	public function customize_set_last_used( $wp_customize ) {
 		$data = $wp_customize->get_setting( 'header_image_data' )->post_value();
 
@@ -1252,6 +1265,10 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 		update_post_meta( $attachment_id, $key, time() );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_default_header_images() {
 		$this->process_default_headers();
 
@@ -1285,10 +1302,13 @@ wp_nonce_field( 'custom-header-options', '_wpnonce-custom-header-options' ); ?>
 		);
 
 		// The rest of the set comes after.
-		$header_images = array_merge( $header_images, $this->default_headers );
+		return array_merge( $header_images, $this->default_headers );
-		return $header_images;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_uploaded_header_images() {
 		$header_images = get_uploaded_header_images();
 		$timestamp_key = '_wp_attachment_custom_header_last_used_' . get_stylesheet();

wp-admin/includes/bookmark.php

@@ -77,7 +77,7 @@ function get_default_link_to_edit() {
  * @global wpdb $wpdb
  *
  * @param int $link_id ID of the link to delete
- * @return bool True
+ * @return true
  */
 function wp_delete_link( $link_id ) {
 	global $wpdb;
@@ -140,7 +140,7 @@ function get_link_to_edit( $link_id ) {
  * @global wpdb $wpdb
  *
  * @param array $linkdata Elements that make up the link to insert.
- * @param bool $wp_error Optional. If true return WP_Error object on failure.
+ * @param bool  $wp_error Optional. If true return WP_Error object on failure.
  * @return int|WP_Error Value 0 or WP_Error on failure. The link ID on success.
  */
 function wp_insert_link( $linkdata, $wp_error = false ) {

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

@@ -53,6 +53,9 @@ class WP_Comments_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can('edit_posts');
 	}
@@ -158,8 +161,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 		 * @param int    $comments_per_page The number of comments to list per page.
 		 * @param string $comment_status    The comment status name. Default 'All'.
 		 */
-		$comments_per_page = apply_filters( 'comments_per_page', $comments_per_page, $comment_status );
+		return apply_filters( 'comments_per_page', $comments_per_page, $comment_status );
-		return $comments_per_page;
 	}
 
 	/**
@@ -230,13 +232,14 @@ class WP_Comments_List_Table extends WP_List_Table {
 		 * @param array $status_links An array of fully-formed status links. Default 'All'.
 		 *                            Accepts 'All', 'Pending', 'Approved', 'Spam', and 'Trash'.
 		 */
-		$status_links = apply_filters( 'comment_status_links', $status_links );
+		return apply_filters( 'comment_status_links', $status_links );
-		return $status_links;
 	}
 
 	/**
 	 *
 	 * @global string $comment_status
+	 *
+	 * @return array
 	 */
 	protected function get_bulk_actions() {
 		global $comment_status;
@@ -266,6 +269,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	 *
 	 * @global string $comment_status
 	 * @global string $comment_type
+	 *
 	 * @param string $which
 	 */
 	protected function extra_tablenav( $which ) {
@@ -321,6 +325,9 @@ class WP_Comments_List_Table extends WP_List_Table {
 		echo '</div>';
 	}
 
+	/**
+	 * @return string|false
+	 */
 	public function current_action() {
 		if ( isset( $_REQUEST['delete_all'] ) || isset( $_REQUEST['delete_all2'] ) )
 			return 'delete_all';
@@ -331,6 +338,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	/**
 	 *
 	 * @global int $post_id
+	 *
 	 * @return array
 	 */
 	public function get_columns() {
@@ -350,6 +358,10 @@ class WP_Comments_List_Table extends WP_List_Table {
 		return $columns;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'author'   => 'comment_author',
@@ -406,6 +418,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	 *
 	 * @global WP_Post $post
 	 * @global object  $comment
+	 *
 	 * @param object $a_comment
 	 */
 	public function single_row( $a_comment ) {
@@ -437,14 +450,13 @@ class WP_Comments_List_Table extends WP_List_Table {
  	 * @param string $column_name Current column name
  	 * @param string $primary Primary column name
  	 *
- 	 * @return string
+ 	 * @return string|void
  	 */
  	protected function handle_row_actions( $comment, $column_name, $primary ) {
  		global $comment_status;
- 
+
  		if ( ! $this->user_can ) {
  			return;
-
 		}
 
 		$post = get_post();
@@ -542,6 +554,10 @@ class WP_Comments_List_Table extends WP_List_Table {
 		return $out;
 	}
 
+	/**
+	 *
+	 * @param object $comment
+	 */
 	public function column_cb( $comment ) {
 		if ( $this->user_can ) { ?>
 		<label class="screen-reader-text" for="cb-select-<?php echo $comment->comment_ID; ?>"><?php _e( 'Select comment' ); ?></label>
@@ -553,6 +569,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	/**
 	 *
 	 * @global string $comment_status
+	 *
 	 * @param object $comment
 	 */
 	public function column_comment( $comment ) {
@@ -601,6 +618,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	/**
 	 *
 	 * @global string $comment_status
+	 *
 	 * @param object $comment
 	 */
 	public function column_author( $comment ) {
@@ -634,6 +652,10 @@ class WP_Comments_List_Table extends WP_List_Table {
 		}
 	}
 
+	/**
+	 *
+	 * @return string
+	 */
 	public function column_date() {
 		return get_comment_date( __( 'Y/m/d \a\t g:i a' ) );
 	}
@@ -666,6 +688,11 @@ class WP_Comments_List_Table extends WP_List_Table {
 			echo $thumb;
 	}
 
+	/**
+	 *
+	 * @param object $comment
+	 * @param string $column_name
+	 */
 	public function column_default( $comment, $column_name ) {
 		/**
 		 * Fires when the default column output is displayed for a single row.
@@ -691,6 +718,10 @@ class WP_Comments_List_Table extends WP_List_Table {
  */
 class WP_Post_Comments_List_Table extends WP_Comments_List_Table {
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_column_info() {
 		return array(
 			array(
@@ -703,12 +734,20 @@ class WP_Post_Comments_List_Table extends WP_Comments_List_Table {
 		);
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_table_classes() {
 		$classes = parent::get_table_classes();
 		$classes[] = 'comments-box';
 		return $classes;
 	}
 
+	/**
+	 *
+	 * @param bool $output_empty
+	 */
 	public function display( $output_empty = false ) {
 		$singular = $this->_args['singular'];
 
@@ -727,6 +766,11 @@ class WP_Post_Comments_List_Table extends WP_Comments_List_Table {
 <?php
 	}
 
+	/**
+	 *
+	 * @param bool $comment_status
+	 * @return int
+	 */
 	public function get_per_page( $comment_status = false ) {
 		return 10;
 	}

wp-admin/includes/class-wp-filesystem-base.php

@@ -171,7 +171,6 @@ class WP_Filesystem_Base {
 	 * @return string|false The location of the remote path, false on failure.
 	 */
 	public function find_folder( $folder ) {
-
 		if ( isset( $this->cache[ $folder ] ) )
 			return $this->cache[ $folder ];
 

wp-admin/includes/class-wp-filesystem-ftpext.php

@@ -17,7 +17,11 @@
 class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 	public $link;
 
-	public function __construct($opt='') {
+	/**
+	 *
+	 * @param array $opt
+	 */
+	public function __construct( $opt = '' ) {
 		$this->method = 'ftpext';
 		$this->errors = new WP_Error();
 
@@ -58,6 +62,10 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 			$this->options['ssl'] = true;
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function connect() {
 		if ( isset($this->options['ssl']) && $this->options['ssl'] && function_exists('ftp_ssl_connect') )
 			$this->link = @ftp_ssl_connect($this->options['hostname'], $this->options['port'], FS_CONNECT_TIMEOUT);

wp-admin/includes/class-wp-filesystem-ftpsockets.php

@@ -20,7 +20,11 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 	 */
 	public $ftp;
 
-	public function __construct($opt = '') {
+	/**
+	 *
+	 * @param array $opt
+	 */
+	public function __construct( $opt  = '' ) {
 		$this->method = 'ftpsockets';
 		$this->errors = new WP_Error();
 
@@ -52,6 +56,10 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 			$this->options['password'] = $opt['password'];
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function connect() {
 		if ( ! $this->ftp )
 			return false;
@@ -226,9 +234,9 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return $dir[$file]['group'];
 	}
 	/**
-	 * @param string $source
+	 * @param string   $source
-	 * @param string $destination
+	 * @param string   $destination
-	 * @param bool $overwrite
+	 * @param bool     $overwrite
 	 * @param int|bool $mode
 	 * @return bool
 	 */
@@ -245,7 +253,7 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 	/**
 	 * @param string $source
 	 * @param string $destination
-	 * @param bool $overwrite
+	 * @param bool   $overwrite
 	 * @return bool
 	 */
 	public function move($source, $destination, $overwrite = false ) {
@@ -253,7 +261,7 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 	}
 	/**
 	 * @param string $file
-	 * @param bool $recursive
+	 * @param bool   $recursive
 	 * @param string $type
 	 * @return bool
 	 */
@@ -359,9 +367,9 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $path
-	 * @param mixed $chmod
+	 * @param mixed  $chmod
-	 * @param mixed $chown
+	 * @param mixed  $chown
-	 * @param mixed $chgrp
+	 * @param mixed  $chgrp
 	 * @return bool
 	 */
 	public function mkdir($path, $chmod = false, $chown = false, $chgrp = false ) {
@@ -387,8 +395,8 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $path
-	 * @param bool $include_hidden
+	 * @param bool   $include_hidden
-	 * @param bool $recursive
+	 * @param bool   $recursive
 	 * @return bool|array
 	 */
 	public function dirlist($path = '.', $include_hidden = true, $recursive = false ) {

wp-admin/includes/class-wp-filesystem-ssh2.php

@@ -42,7 +42,11 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	public $sftp_link;
 	public $keys = false;
 
-	public function __construct($opt='') {
+	/**
+	 *
+	 * @param array $opt
+	 */
+	public function __construct( $opt = '' ) {
 		$this->method = 'ssh2';
 		$this->errors = new WP_Error();
 
@@ -89,9 +93,12 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		} else {
 			$this->options['password'] = $opt['password'];
 		}
-
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function connect() {
 		if ( ! $this->keys ) {
 			$this->link = @ssh2_connect($this->options['hostname'], $this->options['port']);
@@ -126,8 +133,7 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	 * @param bool $returnbool
 	 * @return bool|string
 	 */
-	public function run_command( $command, $returnbool = false) {
+	public function run_command( $command, $returnbool = false ) {
-
 		if ( ! $this->link )
 			return false;
 
@@ -166,8 +172,8 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	}
 
 	/**
-	 * @param string $file
+	 * @param string   $file
-	 * @param string $contents
+	 * @param string   $contents
 	 * @param bool|int $mode
 	 * @return bool
 	 */
@@ -182,6 +188,10 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return true;
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function cwd() {
 		$cwd = $this->run_command('pwd');
 		if ( $cwd ) {
@@ -201,7 +211,9 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	/**
 	 * @param string $file
 	 * @param string $group
-	 * @param bool $recursive
+	 * @param bool   $recursive
+	 *
+	 * @return bool
 	 */
 	public function chgrp($file, $group, $recursive = false ) {
 		if ( ! $this->exists($file) )
@@ -213,8 +225,8 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $file
-	 * @param int $mode
+	 * @param int    $mode
-	 * @param bool $recursive
+	 * @param bool   $recursive
 	 * @return bool|string
 	 */
 	public function chmod($file, $mode = false, $recursive = false) {
@@ -289,9 +301,9 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	}
 
 	/**
-	 * @param string $source
+	 * @param string   $source
-	 * @param string $destination
+	 * @param string   $destination
-	 * @param bool $overwrite
+	 * @param bool     $overwrite
 	 * @param int|bool $mode
 	 * @return bool
 	 */
@@ -307,7 +319,7 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	/**
 	 * @param string $source
 	 * @param string $destination
-	 * @param bool $overwrite
+	 * @param bool   $overwrite
 	 * @return bool
 	 */
 	public function move($source, $destination, $overwrite = false) {
@@ -315,8 +327,8 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	}
 
 	/**
-	 * @param string $file
+	 * @param string      $file
-	 * @param bool $recursive
+	 * @param bool        $recursive
 	 * @param string|bool $type
 	 * @return bool
 	 */
@@ -403,8 +415,8 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $file
-	 * @param int $time
+	 * @param int    $time
-	 * @param int $atime
+	 * @param int    $atime
 	 */
 	public function touch($file, $time = 0, $atime = 0) {
 		//Not implemented.
@@ -412,9 +424,9 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $path
-	 * @param mixed $chmod
+	 * @param mixed  $chmod
-	 * @param mixed $chown
+	 * @param mixed  $chown
-	 * @param mixed $chgrp
+	 * @param mixed  $chgrp
 	 * @return bool
 	 */
 	public function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
@@ -435,7 +447,7 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $path
-	 * @param bool $recursive
+	 * @param bool   $recursive
 	 * @return bool
 	 */
 	public function rmdir($path, $recursive = false) {
@@ -444,8 +456,8 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 
 	/**
 	 * @param string $path
-	 * @param bool $include_hidden
+	 * @param bool   $include_hidden
-	 * @param bool $recursive
+	 * @param bool   $recursive
 	 * @return bool|array
 	 */
 	public function dirlist($path, $include_hidden = true, $recursive = false) {

wp-admin/includes/class-wp-importer.php

@@ -14,6 +14,7 @@ class WP_Importer {
 	 *
 	 * @global wpdb $wpdb
 	 *
+	 * @param string $importer_name
 	 * @param string $bid
 	 * @return array
 	 */
@@ -53,6 +54,7 @@ class WP_Importer {
 	 *
 	 * @global wpdb $wpdb
 	 *
+	 * @param string $importer_name
 	 * @param string $bid
 	 * @return int
 	 */
@@ -120,6 +122,11 @@ class WP_Importer {
 		return $hashtable;
 	}
 
+	/**
+	 *
+	 * @param int $blog_id
+	 * @return int|void
+	 */
 	public function set_blog( $blog_id ) {
 		if ( is_numeric( $blog_id ) ) {
 			$blog_id = (int) $blog_id;
@@ -147,6 +154,11 @@ class WP_Importer {
 		return $blog_id;
 	}
 
+	/**
+	 *
+	 * @param int $user_id
+	 * @return int|void
+	 */
 	public function set_user( $user_id ) {
 		if ( is_numeric( $user_id ) ) {
 			$user_id = (int) $user_id;
@@ -179,7 +191,7 @@ class WP_Importer {
 	 * @param string $url
 	 * @param string $username
 	 * @param string $password
-	 * @param bool $head
+	 * @param bool   $head
 	 * @return array
 	 */
 	public function get_page( $url, $username = '', $password = '', $head = false ) {
@@ -254,7 +266,7 @@ class WP_Importer {
  * Exits when a required param is not set.
  *
  * @param string $param
- * @param bool $required
+ * @param bool   $required
  * @return mixed
  */
 function get_cli_args( $param, $required = false ) {

wp-admin/includes/class-wp-links-list-table.php

@@ -26,6 +26,10 @@ class WP_Links_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can( 'manage_links' );
 	}
@@ -60,6 +64,10 @@ class WP_Links_List_Table extends WP_List_Table {
 		_e( 'No links found.' );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_bulk_actions() {
 		$actions = array();
 		$actions['delete'] = __( 'Delete' );
@@ -99,6 +107,10 @@ class WP_Links_List_Table extends WP_List_Table {
 <?php
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		return array(
 			'cb'         => '<input type="checkbox" />',
@@ -111,6 +123,10 @@ class WP_Links_List_Table extends WP_List_Table {
 		);
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'name'    => 'name',

wp-admin/includes/class-wp-list-table.php

@@ -250,6 +250,8 @@ class WP_List_Table {
 	 *
 	 * @param array $args An associative array with information about the pagination
 	 * @access protected
+	 *
+	 * @param array|string $args
 	 */
 	protected function set_pagination_args( $args ) {
 		$args = wp_parse_args( $args, array(
@@ -455,7 +457,7 @@ class WP_List_Table {
 	 * @since 3.1.0
 	 * @access public
 	 *
-	 * @return string|bool The action name or False if no action was selected
+	 * @return string|false The action name or False if no action was selected
 	 */
 	public function current_action() {
 		if ( isset( $_REQUEST['filter_action'] ) && ! empty( $_REQUEST['filter_action'] ) )
@@ -976,7 +978,6 @@ class WP_List_Table {
 		$singular = $this->_args['singular'];
 
 		$this->display_tablenav( 'top' );
-
 ?>
 <table class="wp-list-table <?php echo implode( ' ', $this->get_table_classes() ); ?>">
 	<thead>
@@ -1092,8 +1093,17 @@ class WP_List_Table {
 		echo '</tr>';
 	}
 
+	/**
+	 *
+	 * @param object $item
+	 * @param string $column_name
+	 */
 	protected function column_default( $item, $column_name ) {}
 
+	/**
+	 *
+	 * @param object $item
+	 */
 	protected function column_cb( $item ) {}
 
 	/**

wp-admin/includes/class-wp-media-list-table.php

@@ -37,6 +37,10 @@ class WP_Media_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can('upload_files');
 	}
@@ -105,6 +109,10 @@ class WP_Media_List_Table extends WP_List_Table {
 		return $type_links;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_bulk_actions() {
 		$actions = array();
 		if ( MEDIA_TRASH ) {
@@ -151,6 +159,10 @@ class WP_Media_List_Table extends WP_List_Table {
 <?php
 	}
 
+	/**
+	 *
+	 * @return string
+	 */
 	public function current_action() {
 		if ( isset( $_REQUEST['found_post_id'] ) && isset( $_REQUEST['media'] ) )
 			return 'attach';
@@ -164,6 +176,10 @@ class WP_Media_List_Table extends WP_List_Table {
 		return parent::current_action();
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function has_items() {
 		return have_posts();
 	}
@@ -221,6 +237,10 @@ class WP_Media_List_Table extends WP_List_Table {
 	<?php
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		$posts_columns = array();
 		$posts_columns['cb'] = '<input type="checkbox" />';
@@ -271,11 +291,13 @@ class WP_Media_List_Table extends WP_List_Table {
 		 * @param bool  $detached      Whether the list table contains media not attached
 		 *                             to any posts. Default true.
 		 */
-		$posts_columns = apply_filters( 'manage_media_columns', $posts_columns, $this->detached );
+		return apply_filters( 'manage_media_columns', $posts_columns, $this->detached );
-
-		return $posts_columns;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'title'    => 'title',
@@ -495,7 +517,7 @@ foreach ( $columns as $column_name => $column_display_name ) {
 		if( $primary === $column_name ) {
 			echo $this->row_actions( $this->_get_row_actions( $post, $att_title ) );
 		}
-		
+
 		echo '</td>';
 	}
 }
@@ -519,6 +541,8 @@ foreach ( $columns as $column_name => $column_display_name ) {
 	/**
 	 * @param WP_Post $post
 	 * @param string  $att_title
+	 *
+	 * @return array
 	 */
 	private function _get_row_actions( $post, $att_title ) {
 		$actions = array();
@@ -567,8 +591,6 @@ foreach ( $columns as $column_name => $column_display_name ) {
 		 * @param bool    $detached Whether the list table contains media not attached
 		 *                          to any posts. Default true.
 		 */
-		$actions = apply_filters( 'media_row_actions', $actions, $post, $this->detached );
+		return apply_filters( 'media_row_actions', $actions, $post, $this->detached );
-
-		return $actions;
 	}
 }

wp-admin/includes/class-wp-ms-sites-list-table.php

@@ -26,6 +26,10 @@ class WP_MS_Sites_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can( 'manage_sites' );
 	}
@@ -142,6 +146,10 @@ class WP_MS_Sites_List_Table extends WP_List_Table {
 		_e( 'No sites found.' );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_bulk_actions() {
 		$actions = array();
 		if ( current_user_can( 'delete_sites' ) )
@@ -166,6 +174,10 @@ class WP_MS_Sites_List_Table extends WP_List_Table {
 			$this->view_switcher( $mode );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		$blogname_columns = ( is_subdomain_install() ) ? __( 'Domain' ) : __( 'Path' );
 		$sites_columns = array(
@@ -187,11 +199,13 @@ class WP_MS_Sites_List_Table extends WP_List_Table {
 		 * @param array $sites_columns An array of displayed site columns. Default 'cb',
 		 *                             'blogname', 'lastupdated', 'registered', 'users'.
 		 */
-		$sites_columns = apply_filters( 'wpmu_blogs_columns', $sites_columns );
+		return apply_filters( 'wpmu_blogs_columns', $sites_columns );
-
-		return $sites_columns;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'blogname'    => 'blogname',

wp-admin/includes/class-wp-ms-themes-list-table.php

@@ -47,11 +47,19 @@ class WP_MS_Themes_List_Table extends WP_List_Table {
 			$this->site_id = isset( $_REQUEST['id'] ) ? intval( $_REQUEST['id'] ) : 0;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_table_classes() {
 		// todo: remove and add CSS for .themes
 		return array( 'widefat', 'plugins' );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		if ( $this->is_site_themes )
 			return current_user_can( 'manage_sites' );
@@ -223,6 +231,10 @@ class WP_MS_Themes_List_Table extends WP_List_Table {
 		);
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'name'         => 'name',
@@ -291,8 +303,8 @@ class WP_MS_Themes_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 *
 	 * @global string $status
+	 *
 	 * @return array
 	 */
 	protected function get_bulk_actions() {
@@ -322,6 +334,7 @@ class WP_MS_Themes_List_Table extends WP_List_Table {
 	 * @global int $page
 	 * @global string $s
 	 * @global array $totals
+	 * 
 	 * @param WP_Theme $theme
 	 */
 	public function single_row( $theme ) {

wp-admin/includes/class-wp-ms-users-list-table.php

@@ -8,7 +8,10 @@
  * @access private
  */
 class WP_MS_Users_List_Table extends WP_List_Table {
-
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can( 'manage_network_users' );
 	}
@@ -79,6 +82,10 @@ class WP_MS_Users_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_bulk_actions() {
 		$actions = array();
 		if ( current_user_can( 'delete_users' ) )
@@ -127,6 +134,10 @@ class WP_MS_Users_List_Table extends WP_List_Table {
 			$this->view_switcher( $mode );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		$users_columns = array(
 			'cb'         => '<input type="checkbox" />',
@@ -144,11 +155,13 @@ class WP_MS_Users_List_Table extends WP_List_Table {
 		 * @param array $users_columns An array of user columns. Default 'cb', 'username',
 		 *                             'name', 'email', 'registered', 'blogs'.
 		 */
-		$users_columns = apply_filters( 'wpmu_users_columns', $users_columns );
+		return apply_filters( 'wpmu_users_columns', $users_columns );
-
-		return $users_columns;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'username'   => 'login',
@@ -208,7 +221,7 @@ class WP_MS_Users_List_Table extends WP_List_Table {
 					<?php
 				} else {
 					echo "<td $attributes>";
-					
+
 					switch ( $column_name ) {
 						case 'username':
 							$avatar	= get_avatar( $user->user_email, 32 );

wp-admin/includes/class-wp-plugin-install-list-table.php

@@ -15,6 +15,10 @@ class WP_Plugin_Install_List_Table extends WP_List_Table {
 
 	private $error;
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can('install_plugins');
 	}
@@ -28,6 +32,8 @@ class WP_Plugin_Install_List_Table extends WP_List_Table {
 	 *
 	 * @since 4.0.0
 	 * @access protected
+	 *
+	 * @return array
 	 */
 	protected function get_installed_plugin_slugs() {
 		$slugs = array();
@@ -221,6 +227,7 @@ class WP_Plugin_Install_List_Table extends WP_List_Table {
 	 *
 	 * @global array $tabs
 	 * @global string $tab
+	 *
 	 * @return array
 	 */
 	protected function get_views() {
@@ -325,10 +332,16 @@ class WP_Plugin_Install_List_Table extends WP_List_Table {
 		}
 	}
 
+	/**
+	 * @return array
+	 */
 	protected function get_table_classes() {
 		return array( 'widefat', $this->_args['plural'] );
 	}
-
+	
+	/**
+	 * @return array
+	 */
 	public function get_columns() {
 		return array();
 	}

wp-admin/includes/class-wp-plugins-list-table.php

@@ -40,10 +40,16 @@ class WP_Plugins_List_Table extends WP_List_Table {
 		$page = $this->get_pagenum();
 	}
 
+	/**
+	 * @return array
+	 */
 	protected function get_table_classes() {
 		return array( 'widefat', $this->_args['plural'] );
 	}
 
+	/**
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can('activate_plugins');
 	}
@@ -216,7 +222,7 @@ class WP_Plugins_List_Table extends WP_List_Table {
 	/**
 	 * @staticvar string $term
 	 * @param array $plugin
-	 * @return boolean
+	 * @return bool
 	 */
 	public function _search_callback( $plugin ) {
 		static $term = null;
@@ -282,6 +288,9 @@ class WP_Plugins_List_Table extends WP_List_Table {
 		);
 	}
 
+	/**
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array();
 	}
@@ -365,7 +374,6 @@ class WP_Plugins_List_Table extends WP_List_Table {
 	/**
 	 * @global string $status
 	 * @param string $which
-	 * @return null
 	 */
 	public function bulk_actions( $which = '' ) {
 		global $status;
@@ -379,7 +387,6 @@ class WP_Plugins_List_Table extends WP_List_Table {
 	/**
 	 * @global string $status
 	 * @param string $which
-	 * @return null
 	 */
 	protected function extra_tablenav( $which ) {
 		global $status;
@@ -399,6 +406,9 @@ class WP_Plugins_List_Table extends WP_List_Table {
 		echo '</div>';
 	}
 
+	/**
+	 * @return string
+	 */
 	public function current_action() {
 		if ( isset($_POST['clear-recent-list']) )
 			return 'clear-recent-list';
@@ -425,6 +435,7 @@ class WP_Plugins_List_Table extends WP_List_Table {
 	 * @global int $page
 	 * @global string $s
 	 * @global array $totals
+	 * 
 	 * @param array $item
 	 */
 	public function single_row( $item ) {

wp-admin/includes/class-wp-posts-list-table.php

@@ -100,6 +100,10 @@ class WP_Posts_List_Table extends WP_List_Table {
 		$this->hierarchical_display = $display;
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can( get_post_type_object( $this->screen->post_type )->cap->edit_posts );
 	}
@@ -147,6 +151,10 @@ class WP_Posts_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function has_items() {
 		return have_posts();
 	}
@@ -163,7 +171,7 @@ class WP_Posts_List_Table extends WP_List_Table {
 	 *
 	 * @since 4.2.0
 	 *
-	 * @return bool Whether the current ivew is the "All" view.
+	 * @return bool Whether the current view is the "All" view.
 	 */
 	protected function is_base_request() {
 		if ( empty( $_GET ) ) {
@@ -254,6 +262,10 @@ class WP_Posts_List_Table extends WP_List_Table {
 		return $status_links;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_bulk_actions() {
 		$actions = array();
 		$post_type_obj = get_post_type_object( $this->screen->post_type );
@@ -323,6 +335,10 @@ class WP_Posts_List_Table extends WP_List_Table {
 <?php
 	}
 
+	/**
+	 *
+	 * @return string
+	 */
 	public function current_action() {
 		if ( isset( $_REQUEST['delete_all'] ) || isset( $_REQUEST['delete_all2'] ) )
 			return 'delete_all';
@@ -343,10 +359,18 @@ class WP_Posts_List_Table extends WP_List_Table {
 			$this->view_switcher( $mode );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_table_classes() {
 		return array( 'widefat', 'fixed', 'striped', is_post_type_hierarchical( $this->screen->post_type ) ? 'pages' : 'posts' );
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		$post_type = $this->screen->post_type;
 
@@ -427,11 +451,13 @@ class WP_Posts_List_Table extends WP_List_Table {
 		 *
 		 * @param array $post_columns An array of column names.
 		 */
-		$posts_columns = apply_filters( "manage_{$post_type}_posts_columns", $posts_columns );
+		return apply_filters( "manage_{$post_type}_posts_columns", $posts_columns );
-
-		return $posts_columns;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'title'    => 'title',
@@ -488,7 +514,6 @@ class WP_Posts_List_Table extends WP_List_Table {
 	 * @param array $pages
 	 * @param int $pagenum
 	 * @param int $per_page
-	 * @return false|null
 	 */
 	private function _display_rows_hierarchical( $pages, $pagenum = 1, $per_page = 20 ) {
 		global $wpdb;
@@ -499,7 +524,7 @@ class WP_Posts_List_Table extends WP_List_Table {
 			$pages = get_pages( array( 'sort_column' => 'menu_order' ) );
 
 			if ( ! $pages )
-				return false;
+				return;
 		}
 
 		/*
@@ -596,7 +621,6 @@ class WP_Posts_List_Table extends WP_List_Table {
 	 * @param array $to_display List of pages to be displayed. Passed by reference.
 	 */
 	private function _page_rows( &$children_pages, &$count, $parent, $level, $pagenum, $per_page, &$to_display ) {
-
 		if ( ! isset( $children_pages[$parent] ) )
 			return;
 
@@ -604,7 +628,6 @@ class WP_Posts_List_Table extends WP_List_Table {
 		$end = $start + $per_page;
 
 		foreach ( $children_pages[$parent] as $page ) {
-
 			if ( $count >= $end )
 				break;
 

wp-admin/includes/class-wp-terms-list-table.php

@@ -55,6 +55,10 @@ class WP_Terms_List_Table extends WP_List_Table {
 
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can( get_taxonomy( $this->screen->taxonomy )->cap->manage_terms );
 	}
@@ -114,6 +118,10 @@ class WP_Terms_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function has_items() {
 		// todo: populate $this->items in prepare_items()
 		return true;
@@ -123,6 +131,10 @@ class WP_Terms_List_Table extends WP_List_Table {
 		echo get_taxonomy( $this->screen->taxonomy )->labels->not_found;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_bulk_actions() {
 		$actions = array();
 		$actions['delete'] = __( 'Delete' );
@@ -130,6 +142,10 @@ class WP_Terms_List_Table extends WP_List_Table {
 		return $actions;
 	}
 
+	/**
+	 *
+	 * @return string
+	 */
 	public function current_action() {
 		if ( isset( $_REQUEST['action'] ) && isset( $_REQUEST['delete_tags'] ) && ( 'delete' == $_REQUEST['action'] || 'delete' == $_REQUEST['action2'] ) )
 			return 'bulk-delete';
@@ -137,6 +153,10 @@ class WP_Terms_List_Table extends WP_List_Table {
 		return parent::current_action();
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		$columns = array(
 			'cb'          => '<input type="checkbox" />',
@@ -154,6 +174,10 @@ class WP_Terms_List_Table extends WP_List_Table {
 		return $columns;
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	protected function get_sortable_columns() {
 		return array(
 			'name'        => 'name',
@@ -217,11 +241,11 @@ class WP_Terms_List_Table extends WP_List_Table {
 	 * @param string $taxonomy
 	 * @param array $terms
 	 * @param array $children
-	 * @param int $start
+	 * @param int   $start
-	 * @param int $per_page
+	 * @param int   $per_page
-	 * @param int $count
+	 * @param int   $count
-	 * @param int $parent
+	 * @param int   $parent
-	 * @param int $level
+	 * @param int   $level
 	 */
 	private function _rows( $taxonomy, $terms, &$children, $start, $per_page, &$count, $parent = 0, $level = 0 ) {
 

wp-admin/includes/class-wp-theme-install-list-table.php

@@ -11,6 +11,10 @@ class WP_Theme_Install_List_Table extends WP_Themes_List_Table {
 
 	public $features = array();
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		return current_user_can( 'install_themes' );
 	}
@@ -416,6 +420,8 @@ class WP_Theme_Install_List_Table extends WP_Themes_List_Table {
 	 *
 	 * @global string $tab  Current tab within Themes->Install screen
 	 * @global string $type Type of search.
+	 *
+	 * @param array $extra_args Unused.
 	 */
 	public function _js_vars( $extra_args = array() ) {
 		global $tab, $type;

wp-admin/includes/class-wp-themes-list-table.php

@@ -29,6 +29,10 @@ class WP_Themes_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 *
+	 * @return bool
+	 */
 	public function ajax_user_can() {
 		// Do not check edit_theme_options here. AJAX calls for available themes require switch_themes.
 		return current_user_can( 'switch_themes' );
@@ -97,7 +101,6 @@ class WP_Themes_List_Table extends WP_List_Table {
 
 	/**
 	 * @param string $which
-	 * @return null
 	 */
 	public function tablenav( $which = 'top' ) {
 		if ( $this->get_pagination_arg( 'total_pages' ) <= 1 )
@@ -124,6 +127,10 @@ class WP_Themes_List_Table extends WP_List_Table {
 <?php
 	}
 
+	/**
+	 *
+	 * @return array
+	 */
 	public function get_columns() {
 		return array();
 	}

wp-admin/includes/class-wp-users-list-table.php

@@ -56,6 +56,8 @@ class WP_Users_List_Table extends WP_List_Table {
 	 *
  	 * @since 3.1.0
 	 * @access public
+	 *
+	 * @return bool
 	 */
 	public function ajax_user_can() {
 		if ( $this->is_site_users )

wp-admin/includes/comment.php

@@ -20,11 +20,11 @@
 function comment_exists($comment_author, $comment_date) {
 	global $wpdb;
 
-	$comment_author = stripslashes($comment_author);
-	$comment_date = stripslashes($comment_date);
-
 	return $wpdb->get_var( $wpdb->prepare("SELECT comment_post_ID FROM $wpdb->comments
-			WHERE comment_author = %s AND comment_date = %s", $comment_author, $comment_date) );
+			WHERE comment_author = %s AND comment_date = %s",
+			stripslashes( $comment_author ),
+			stripslashes( $comment_date )
+	) );
 }
 
 /**
@@ -33,7 +33,6 @@ function comment_exists($comment_author, $comment_date) {
  * @since 2.0.0
  */
 function edit_comment() {
-
 	if ( ! current_user_can( 'edit_comment', (int) $_POST['comment_ID'] ) )
 		wp_die ( __( 'You are not allowed to edit comments on this post.' ) );
 
@@ -80,7 +79,7 @@ function edit_comment() {
  * @since 2.0.0
  *
  * @param int $id ID of comment to retrieve.
- * @return bool|object Comment if found. False on failure.
+ * @return object|false Comment if found. False on failure.
  */
 function get_comment_to_edit( $id ) {
 	if ( !$comment = get_comment($id) )
@@ -156,7 +155,7 @@ function get_pending_comments_num( $post_id ) {
  * Add avatars to relevant places in admin, or try to.
  *
  * @since 2.5.0
- * 
+ *
  * @global object $comment
  *
  * @param string $name User name.

wp-admin/includes/template.php

@@ -438,10 +438,10 @@ function get_inline_data($post) {
  *
  * @global WP_List_Table $wp_list_table
  *
- * @param int $position
+ * @param int    $position
- * @param bool $checkbox
+ * @param bool   $checkbox
  * @param string $mode
- * @param bool $table_row
+ * @param bool   $table_row
  */
 function wp_comment_reply( $position = 1, $checkbox = false, $mode = 'single', $table_row = true ) {
 	global $wp_list_table;
@@ -1038,9 +1038,9 @@ function add_meta_box( $id, $title, $callback, $screen = null, $context = 'advan
  * @global array $wp_meta_boxes
  *
  * @staticvar bool $already_sorted
- * @param string|WP_Screen $screen Screen identifier
+ * @param string|WP_Screen $screen  Screen identifier
- * @param string $context box context
+ * @param string           $context box context
- * @param mixed $object gets passed to the box callback function as first parameter
+ * @param mixed            $object  gets passed to the box callback function as first parameter
  * @return int number of meta_boxes
  */
 function do_meta_boxes( $screen, $context, $object ) {
@@ -1107,9 +1107,9 @@ function do_meta_boxes( $screen, $context, $object ) {
  *
  * @global array $wp_meta_boxes
  *
- * @param string $id String for use in the 'id' attribute of tags.
+ * @param string        $id      String for use in the 'id' attribute of tags.
- * @param string|object $screen The screen on which to show the box (post, page, link).
+ * @param string|object $screen  The screen on which to show the box (post, page, link).
- * @param string $context The context within the page where the boxes should show ('normal', 'advanced').
+ * @param string        $context The context within the page where the boxes should show ('normal', 'advanced').
  */
 function remove_meta_box($id, $screen, $context) {
 	global $wp_meta_boxes;
@@ -1143,9 +1143,9 @@ function remove_meta_box($id, $screen, $context) {
  *
  * @uses global $wp_meta_boxes Used to retrieve registered meta boxes.
  *
- * @param string|object $screen The screen identifier.
+ * @param string|object $screen  The screen identifier.
- * @param string $context The meta box context.
+ * @param string        $context The meta box context.
- * @param mixed $object gets passed to the section callback function as first parameter.
+ * @param mixed         $object  gets passed to the section callback function as first parameter.
  * @return int number of meta boxes as accordion sections.
  */
 function do_accordion_sections( $screen, $context, $object ) {
@@ -1221,10 +1221,10 @@ function do_accordion_sections( $screen, $context, $object ) {
  *
  * @global $wp_settings_sections Storage array of all settings sections added to admin pages
  *
- * @param string $id Slug-name to identify the section. Used in the 'id' attribute of tags.
+ * @param string $id       Slug-name to identify the section. Used in the 'id' attribute of tags.
- * @param string $title Formatted title of the section. Shown as the heading for the section.
+ * @param string $title    Formatted title of the section. Shown as the heading for the section.
  * @param string $callback Function that echos out any content at the top of the section (between heading and fields).
- * @param string $page The slug-name of the settings page on which to show the section. Built-in pages include 'general', 'reading', 'writing', 'discussion', 'media', etc. Create your own using add_options_page();
+ * @param string $page     The slug-name of the settings page on which to show the section. Built-in pages include 'general', 'reading', 'writing', 'discussion', 'media', etc. Create your own using add_options_page();
  */
 function add_settings_section($id, $title, $callback, $page) {
 	global $wp_settings_sections;
@@ -1700,6 +1700,10 @@ function iframe_footer() {
 <?php
 }
 
+/**
+ *
+ * @param WP_Post $post
+ */
 function _post_states($post) {
 	$post_states = array();
 	if ( isset( $_REQUEST['post_status'] ) )
@@ -1750,6 +1754,10 @@ function _post_states($post) {
 
 }
 
+/**
+ *
+ * @param WP_Post $post
+ */
 function _media_states( $post ) {
 	$media_states = array();
 	$stylesheet = get_option('stylesheet');

wp-admin/includes/theme-install.php

@@ -50,6 +50,8 @@ function install_themes_feature_list() {
  * Display search form for searching themes.
  *
  * @since 2.8.0
+ *
+ * @param bool $type_selector
  */
 function install_theme_search_form( $type_selector = true ) {
 	$type = isset( $_REQUEST['type'] ) ? wp_unslash( $_REQUEST['type'] ) : 'term';
@@ -150,6 +152,8 @@ function install_themes_upload() {
  * @deprecated 3.4.0
  *
  * @global WP_Theme_Install_List_Table $wp_list_table
+ *
+ * @param object $theme
  */
 function display_theme( $theme ) {
 	_deprecated_function( __FUNCTION__, '3.4' );

wp-admin/includes/theme.php

@@ -15,7 +15,7 @@
  *
  * @param string $stylesheet Stylesheet of the theme to delete
  * @param string $redirect Redirect to page when complete.
- * @return mixed
+ * @return void|bool|WP_Error When void, echoes content.
  */
 function delete_theme($stylesheet, $redirect = '') {
 	global $wp_filesystem;
@@ -123,7 +123,7 @@ function _get_template_edit_filename($fullpath, $containingfolder) {
  * @since 2.7.0
  * @see get_theme_update_available()
  *
- * @param object $theme Theme data object.
+ * @param WP_Theme $theme Theme data object.
  */
 function theme_update_available( $theme ) {
 	echo get_theme_update_available( $theme );

wp-admin/includes/update-core.php

@@ -777,7 +777,7 @@ $_new_bundled_files = array(
  * @global string             $required_mysql_version
  *
  * @param string $from New release unzipped path.
- * @param string $to Path to old WordPress installation.
+ * @param string $to   Path to old WordPress installation.
  * @return WP_Error|null WP_Error on failure, null on success.
  */
 function update_core($from, $to) {
@@ -1118,8 +1118,8 @@ function update_core($from, $to) {
  *
  * @global WP_Filesystem_Base $wp_filesystem
  *
- * @param string $from source directory
+ * @param string $from     source directory
- * @param string $to destination directory
+ * @param string $to       destination directory
  * @param array $skip_list a list of files/folders to skip copying
  * @return mixed WP_Error on failure, True on success.
  */
@@ -1176,6 +1176,8 @@ function _copy_dir($from, $to, $skip_list = array() ) {
  * @global string $wp_version
  * @global string $pagenow
  * @global string $action
+ *
+ * @param string $new_version
  */
 function _redirect_to_about_wordpress( $new_version ) {
 	global $wp_version, $pagenow, $action;

wp-admin/includes/update.php

@@ -9,7 +9,7 @@
 /**
  * Selects the first update version from the update_core option.
  *
- * @return bool|object The response from the API on success, false on failure.
+ * @return object|array|false The response from the API on success, false on failure.
  */
 function get_preferred_from_update_core() {
 	$updates = get_core_updates();
@@ -24,8 +24,8 @@ function get_preferred_from_update_core() {
  * Get available core updates.
  *
  * @param array $options Set $options['dismissed'] to true to show dismissed upgrades too,
- * 	set $options['available'] to false to skip not-dismissed updates.
+ * 	                     set $options['available'] to false to skip not-dismissed updates.
- * @return bool|array Array of the update objects on success, false on failure.
+ * @return array|false Array of the update objects on success, false on failure.
  */
 function get_core_updates( $options = array() ) {
 	$options = array_merge( array( 'available' => true, 'dismissed' => false ), $options );
@@ -67,7 +67,7 @@ function get_core_updates( $options = array() ) {
  *
  * @since 3.7.0
  *
- * @return bool|array False on failure, otherwise the core update offering.
+ * @return array|false False on failure, otherwise the core update offering.
  */
 function find_core_auto_update() {
 	$updates = get_site_transient( 'update_core' );
@@ -128,12 +128,23 @@ function get_core_checksums( $version, $locale ) {
 	return $body['checksums'];
 }
 
+/**
+ *
+ * @param object $update
+ * @return bool
+ */
 function dismiss_core_update( $update ) {
 	$dismissed = get_site_option( 'dismissed_update_core' );
 	$dismissed[ $update->current . '|' . $update->locale ] = true;
 	return update_site_option( 'dismissed_update_core', $dismissed );
 }
 
+/**
+ *
+ * @param string $version
+ * @param string $locale
+ * @return bool
+ */
 function undismiss_core_update( $version, $locale ) {
 	$dismissed = get_site_option( 'dismissed_update_core' );
 	$key = $version . '|' . $locale;
@@ -145,6 +156,12 @@ function undismiss_core_update( $version, $locale ) {
 	return update_site_option( 'dismissed_update_core', $dismissed );
 }
 
+/**
+ *
+ * @param string $version
+ * @param string $locale
+ * @return object|false
+ */
 function find_core_update( $version, $locale ) {
 	$from_api = get_site_transient( 'update_core' );
 
@@ -159,6 +176,11 @@ function find_core_update( $version, $locale ) {
 	return false;
 }
 
+/**
+ *
+ * @param string $msg
+ * @return string
+ */
 function core_update_footer( $msg = '' ) {
 	if ( !current_user_can('update_core') )
 		return sprintf( __( 'Version %s' ), get_bloginfo( 'version', 'display' ) );
@@ -264,6 +286,12 @@ function wp_plugin_update_rows() {
 	}
 }
 
+/**
+ *
+ * @param string $file
+ * @param array  $plugin_data
+ * @return false|void
+ */
 function wp_plugin_update_row( $file, $plugin_data ) {
 	$current = get_site_transient( 'update_plugins' );
 	if ( !isset( $current->response[ $file ] ) )
@@ -330,6 +358,10 @@ function wp_plugin_update_row( $file, $plugin_data ) {
 	}
 }
 
+/**
+ *
+ * @return array
+ */
 function get_theme_updates() {
 	$current = get_site_transient('update_themes');
 
@@ -359,6 +391,12 @@ function wp_theme_update_rows() {
 	}
 }
 
+/**
+ *
+ * @param string   $theme_key
+ * @param WP_Theme $theme
+ * @return false|void
+ */
 function wp_theme_update_row( $theme_key, $theme ) {
 	$current = get_site_transient( 'update_themes' );
 	if ( !isset( $current->response[ $theme_key ] ) )

wp-admin/includes/upgrade.php

@@ -165,22 +165,22 @@ function wp_install_defaults( $user_id ) {
 	}
 
 	$wpdb->insert( $wpdb->posts, array(
-								'post_author' => $user_id,
+		'post_author' => $user_id,
-								'post_date' => $now,
+		'post_date' => $now,
-								'post_date_gmt' => $now_gmt,
+		'post_date_gmt' => $now_gmt,
-								'post_content' => $first_post,
+		'post_content' => $first_post,
-								'post_excerpt' => '',
+		'post_excerpt' => '',
-								'post_title' => __('Hello world!'),
+		'post_title' => __('Hello world!'),
-								/* translators: Default post slug */
+		/* translators: Default post slug */
-								'post_name' => sanitize_title( _x('hello-world', 'Default post slug') ),
+		'post_name' => sanitize_title( _x('hello-world', 'Default post slug') ),
-								'post_modified' => $now,
+		'post_modified' => $now,
-								'post_modified_gmt' => $now_gmt,
+		'post_modified_gmt' => $now_gmt,
-								'guid' => $first_post_guid,
+		'guid' => $first_post_guid,
-								'comment_count' => 1,
+		'comment_count' => 1,
-								'to_ping' => '',
+		'to_ping' => '',
-								'pinged' => '',
+		'pinged' => '',
-								'post_content_filtered' => ''
+		'post_content_filtered' => ''
-								));
+	));
 	$wpdb->insert( $wpdb->term_relationships, array('term_taxonomy_id' => $cat_tt_id, 'object_id' => 1) );
 
 	// Default comment
@@ -194,14 +194,14 @@ To delete a comment, just log in and view the post's comments. There you wi
 		$first_comment = get_site_option( 'first_comment', $first_comment );
 	}
 	$wpdb->insert( $wpdb->comments, array(
-								'comment_post_ID' => 1,
+		'comment_post_ID' => 1,
-								'comment_author' => $first_comment_author,
+		'comment_author' => $first_comment_author,
-								'comment_author_email' => '',
+		'comment_author_email' => '',
-								'comment_author_url' => $first_comment_url,
+		'comment_author_url' => $first_comment_url,
-								'comment_date' => $now,
+		'comment_date' => $now,
-								'comment_date_gmt' => $now_gmt,
+		'comment_date_gmt' => $now_gmt,
-								'comment_content' => $first_comment
+		'comment_content' => $first_comment
-								));
+	));
 
 	// First Page
 	$first_page = sprintf( __( "This is an example page. It's different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this:
@@ -217,22 +217,22 @@ As a new WordPress user, you should go to <a href=\"%s\">your dashboard</a> to d
 		$first_page = get_site_option( 'first_page', $first_page );
 	$first_post_guid = get_option('home') . '/?page_id=2';
 	$wpdb->insert( $wpdb->posts, array(
-								'post_author' => $user_id,
+		'post_author' => $user_id,
-								'post_date' => $now,
+		'post_date' => $now,
-								'post_date_gmt' => $now_gmt,
+		'post_date_gmt' => $now_gmt,
-								'post_content' => $first_page,
+		'post_content' => $first_page,
-								'post_excerpt' => '',
+		'post_excerpt' => '',
-								'post_title' => __( 'Sample Page' ),
+		'post_title' => __( 'Sample Page' ),
-								/* translators: Default page slug */
+		/* translators: Default page slug */
-								'post_name' => __( 'sample-page' ),
+		'post_name' => __( 'sample-page' ),
-								'post_modified' => $now,
+		'post_modified' => $now,
-								'post_modified_gmt' => $now_gmt,
+		'post_modified_gmt' => $now_gmt,
-								'guid' => $first_post_guid,
+		'guid' => $first_post_guid,
-								'post_type' => 'page',
+		'post_type' => 'page',
-								'to_ping' => '',
+		'to_ping' => '',
-								'pinged' => '',
+		'pinged' => '',
-								'post_content_filtered' => ''
+		'post_content_filtered' => ''
-								));
+	));
 	$wpdb->insert( $wpdb->postmeta, array( 'post_id' => 2, 'meta_key' => '_wp_page_template', 'meta_value' => 'default' ) );
 
 	// Set up default widgets for default theme.
@@ -392,8 +392,6 @@ if ( !function_exists('wp_upgrade') ) :
  * @global int  $wp_current_db_version
  * @global int  $wp_db_version
  * @global wpdb $wpdb
- *
- * @return null If no update is necessary or site isn't completely installed, null.
  */
 function wp_upgrade() {
 	global $wp_current_db_version, $wp_db_version, $wpdb;
@@ -445,8 +443,6 @@ endif;
  *
  * @global int $wp_current_db_version
  * @global int $wp_db_version
- *
- * @return null If no update is necessary, null.
  */
 function upgrade_all() {
 	global $wp_current_db_version, $wp_db_version;
@@ -1747,7 +1743,7 @@ function maybe_create_table($table_name, $create_ddl) {
  *
  * @param string $table Database table name.
  * @param string $index Index name to drop.
- * @return bool True, when finished.
+ * @return true True, when finished.
  */
 function drop_index($table, $index) {
 	global $wpdb;
@@ -1770,7 +1766,7 @@ function drop_index($table, $index) {
  *
  * @param string $table Database table name.
  * @param string $index Database table index column.
- * @return bool True, when done with execution.
+ * @return true True, when done with execution.
  */
 function add_clean_index($table, $index) {
 	global $wpdb;
@@ -1789,7 +1785,7 @@ function add_clean_index($table, $index) {
  * @param string $table_name  The table name to modify.
  * @param string $column_name The column name to add to the table.
  * @param string $create_ddl  The SQL statement used to add the column.
- * @return True if already exists or on successful completion, false on error.
+ * @return bool True if already exists or on successful completion, false on error.
  */
 function maybe_add_column($table_name, $column_name, $create_ddl) {
 	global $wpdb;
@@ -2278,7 +2274,7 @@ function make_site_theme_from_oldschool($theme_name, $template) {
 
 				// Don't copy anything.
 				continue;
-				}
+			}
 		}
 
 		if (! @copy("$oldpath/$oldfile", "$site_dir/$newfile"))
@@ -2331,7 +2327,7 @@ function make_site_theme_from_oldschool($theme_name, $template) {
  *
  * @param string $theme_name The name of the theme.
  * @param string $template   The directory name of the theme.
- * @return null|false
+ * @return false|void
  */
 function make_site_theme_from_default($theme_name, $template) {
 	$site_dir = WP_CONTENT_DIR . "/themes/$template";

wp-admin/includes/user.php

@@ -11,7 +11,7 @@
  *
  * @since 2.0.0
  *
- * @return null|WP_Error|int Null when adding user, WP_Error or User ID integer when no parameters.
+ * @return int|WP_Error WP_Error or User ID.
  */
 function add_user() {
 	return edit_user();
@@ -25,7 +25,7 @@ function add_user() {
  * @since 2.0.0
  *
  * @param int $user_id Optional. User ID.
- * @return int user id of the updated user
+ * @return int|WP_Error user id of the updated user
  */
 function edit_user( $user_id = 0 ) {
 	$wp_roles = wp_roles();
@@ -410,6 +410,9 @@ function default_password_nag_handler($errors = false) {
 
 /**
  * @since 2.8.0
+ *
+ * @param int    $user_ID
+ * @param object $old_data
  */
 function default_password_nag_edit_user($user_ID, $old_data) {
 	// Short-circuit it.

wp-admin/includes/widgets.php

@@ -54,6 +54,8 @@ function wp_list_widgets() {
  *
  * @since 3.1.0
  * @access private
+ *
+ * @return int
  */
 function _sort_name_callback( $a, $b ) {
 	return strnatcasecmp( $a['name'], $b['name'] );

wp-admin/install-helper.php

@@ -157,12 +157,12 @@ function maybe_drop_column($table_name, $column_name, $drop_ddl) {
  * @global wpdb $wpdb
  *
  * @param string $table_name Table name
- * @param string $col_name Column name
+ * @param string $col_name   Column name
- * @param string $col_type Column type
+ * @param string $col_type   Column type
- * @param bool $is_null Optional. Check is null.
+ * @param bool   $is_null    Optional. Check is null.
- * @param mixed $key Optional. Key info.
+ * @param mixed  $key        Optional. Key info.
- * @param mixed $default Optional. Default value.
+ * @param mixed  $default    Optional. Default value.
- * @param mixed $extra Optional. Extra value.
+ * @param mixed  $extra      Optional. Extra value.
  * @return bool True, if matches. False, if not matching.
  */
 function check_column($table_name, $col_name, $col_type, $is_null = null, $key = null, $default = null, $extra = null) {

wp-admin/install.php

@@ -52,6 +52,8 @@ $step = isset( $_GET['step'] ) ? (int) $_GET['step'] : 0;
  * Display install header.
  *
  * @since 2.5.0
+ *
+ * @param string $body_classes
  */
 function display_header( $body_classes = '' ) {
 	header( 'Content-Type: text/html; charset=utf-8' );
@@ -82,6 +84,8 @@ function display_header( $body_classes = '' ) {
  * Display installer setup form.
  *
  * @since 2.8.0
+ *
+ * @param string|null $error
  */
 function display_setup_form( $error = null ) {
 	global $wpdb;

wp-admin/load-styles.php

@@ -81,6 +81,11 @@ function admin_url() {}
  */
 function wp_guess_url() {}
 
+/**
+ *
+ * @param string $path
+ * @return string
+ */
 function get_file($path) {
 
 	if ( function_exists('realpath') )

wp-admin/menu.php

@@ -170,8 +170,12 @@ $menu[60] = array( __( 'Appearance' ), $appearance_cap, 'themes.php', '', 'menu-
 unset( $appearance_cap );
 
 // Add 'Editor' to the bottom of the Appearance menu.
-if ( ! is_multisite() )
+if ( ! is_multisite() ) {
 	add_action('admin_menu', '_add_themes_utility_last', 101);
+}
+/**
+ *
+ */
 function _add_themes_utility_last() {
 	// Must use API on the admin_menu hook, direct modification is only possible on/before the _admin_menu hook
 	add_submenu_page('themes.php', _x('Editor', 'theme editor'), _x('Editor', 'theme editor'), 'edit_themes', 'theme-editor.php');

wp-admin/network.php

@@ -157,6 +157,8 @@ include( ABSPATH . 'wp-admin/admin-header.php' );
  * @since 3.0.0
  *
  * @global bool $is_apache
+ *
+ * @param WP_Error $errors
  */
 function network_step1( $errors = false ) {
 	global $is_apache;
@@ -336,6 +338,8 @@ function network_step1( $errors = false ) {
  * @since 3.0.0
  *
  * @global wpdb $wpdb
+ *
+ * @param WP_Error $errors
  */
 function network_step2( $errors = false ) {
 	global $wpdb;

wp-admin/network/users.php

@@ -16,6 +16,10 @@ if ( ! is_multisite() )
 if ( ! current_user_can( 'manage_network_users' ) )
 	wp_die( __( 'You do not have permission to access this page.' ), 403 );
 
+/**
+ *
+ * @param array $users
+ */
 function confirm_delete_users( $users ) {
 	$current_user = wp_get_current_user();
 	if ( ! is_array( $users ) || empty( $users ) ) {

wp-admin/plugins.php

@@ -148,6 +148,9 @@ if ( $action ) {
 
 			@ini_set('display_errors', true); //Ensure that Fatal errors are displayed.
 			// Go back to "sandbox" scope so we get the same errors as before
+			/**
+			 * @param string $plugin
+			 */
 			function plugin_sandbox_scrape( $plugin ) {
 				wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin );
 				include( WP_PLUGIN_DIR . '/' . $plugin );

wp-admin/post.php

@@ -59,7 +59,7 @@ function redirect_post($post_id = '') {
 					$message = 6;
 			}
 		} else {
-				$message = 'draft' == $status ? 10 : 1;
+			$message = 'draft' == $status ? 10 : 1;
 		}
 
 		$location = add_query_arg( 'message', $message, get_edit_post_link( $post_id, 'url' ) );

wp-admin/setup-config.php

@@ -64,12 +64,12 @@ $step = isset( $_GET['step'] ) ? (int) $_GET['step'] : -1;
  * @ignore
  * @since 2.3.0
  *
- * @global string    $wp_version
  * @global string    $wp_local_package
  * @global WP_Locale $wp_locale
+ *
+ * @param string|array $body_classes
  */
 function setup_config_display_header( $body_classes = array() ) {
-	global $wp_version;
 	$body_classes = (array) $body_classes;
 	$body_classes[] = 'wp-core-ui';
 	if ( is_rtl() ) {

wp-admin/update-core.php

@@ -314,7 +314,6 @@ function list_theme_updates() {
 	}
 
 	$form_action = 'update-core.php?action=do-theme-upgrade';
-
 ?>
 <h3><?php _e( 'Themes' ); ?></h3>
 <p><?php _e( 'The following themes have new versions available. Check the ones you want to update and then click &#8220;Update Themes&#8221;.' ); ?></p>
@@ -381,6 +380,8 @@ function list_translation_updates() {
  * @since 2.7.0
  *
  * @global WP_Filesystem_Base $wp_filesystem Subclass
+ *
+ * @param bool $reinstall
  */
 function do_core_upgrade( $reinstall = false ) {
 	global $wp_filesystem;

wp-admin/user-new.php

@@ -17,6 +17,11 @@ if ( is_multisite() ) {
 }
 
 if ( is_multisite() ) {
+	/**
+	 *
+	 * @param string $text
+	 * @return string
+	 */
 	function admin_created_user_email( $text ) {
 		$roles = get_editable_roles();
 		$role = $roles[ $_REQUEST['role'] ];

wp-admin/widgets.php

@@ -21,6 +21,11 @@ if ( isset($_GET['widgets-access']) ) {
 	set_user_setting( 'widgets_access', $widgets_access );
 }
 
+/**
+ *
+ * @param string $classes
+ * @return string
+ */
 function wp_widgets_access_body_class($classes) {
 	return "$classes widgets_access ";
 }

wp-includes/version.php

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