Improve inline documentation for `WP_Users_List_Table`.

Props leewillis77 for the initial patch.
Fixes #26564.

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


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

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

@@ -2,16 +2,38 @@
 /**
  * Users List Table class.
  *
- * @package WordPress
- * @subpackage List_Table
  * @since 3.1.0
  * @access private
+ *
+ * @package WordPress
+ * @subpackage List_Table
  */
 class WP_Users_List_Table extends WP_List_Table {
 
+	/**
+	 * Site ID to generate the Users list table for.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 * @var int
+	 */
 	var $site_id;
+
+	/**
+	 * Whether or not the current Users list table is for Multisite.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 * @var bool
+	 */
 	var $is_site_users;
 
+	/**
+	 * Constructor.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 */
 	function __construct( $args = array() ) {
 		parent::__construct( array(
 			'singular' => 'user',
@@ -25,6 +47,12 @@ class WP_Users_List_Table extends WP_List_Table {
 			$this->site_id = isset( $_REQUEST['id'] ) ? intval( $_REQUEST['id'] ) : 0;
 	}
 
+	/**
+	 * Check the current user's permissions.
+	 *
+ 	 * @since 3.1.0
+	 * @access public
+	 */
 	function ajax_user_can() {
 		if ( $this->is_site_users )
 			return current_user_can( 'manage_sites' );
@@ -32,6 +60,12 @@ class WP_Users_List_Table extends WP_List_Table {
 			return current_user_can( 'list_users' );
 	}
 
+	/**
+	 * Prepare the users list for display.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 */
 	function prepare_items() {
 		global $role, $usersearch;
 
@@ -75,10 +109,28 @@ class WP_Users_List_Table extends WP_List_Table {
 		) );
 	}
 
+	/**
+	 * Output 'no users' message.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 */
 	function no_items() {
 		_e( 'No matching users were found.' );
 	}
 
+	/**
+	 * Return an associative array listing all the views that can be used
+	 * with this table.
+	 *
+	 * Provides a list of roles and user count for that role for easy
+	 * filtering of the user table.
+	 *
+	 * @since  3.1.0
+	 * @access public
+	 *
+	 * @return array An array of HTML links, one for each view.
+	 */
 	function get_views() {
 		global $wp_roles, $role;
 
@@ -119,6 +171,14 @@ class WP_Users_List_Table extends WP_List_Table {
 		return $role_links;
 	}
 
+	/**
+	 * Retrieve an associative array of bulk actions available on this table.
+	 *
+	 * @since  3.1.0
+	 * @access public
+	 *
+	 * @return array Array of bulk actions.
+	 */
 	function get_bulk_actions() {
 		$actions = array();
 
@@ -133,6 +193,15 @@ class WP_Users_List_Table extends WP_List_Table {
 		return $actions;
 	}
 
+	/**
+	 * Output the controls to allow user roles to be changed in bulk.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 *
+	 * @param string $which Whether this is being invoked above ("top")
+	 *                      or below the table ("bottom").
+	 */
 	function extra_tablenav( $which ) {
 		if ( 'top' != $which )
 			return;
@@ -152,6 +221,17 @@ class WP_Users_List_Table extends WP_List_Table {
 		echo '</div>';
 	}
 
+	/**
+	 * Capture the bulk action required, and return it.
+	 *
+	 * Overridden from the base class implementation to capture
+	 * the role change drop-down.
+	 *
+	 * @since  3.1.0
+	 * @access public
+	 *
+	 * @return string The bulk action required.
+	 */
 	function current_action() {
 		if ( isset($_REQUEST['changeit']) && !empty($_REQUEST['new_role']) )
 			return 'promote';
@@ -159,6 +239,15 @@ class WP_Users_List_Table extends WP_List_Table {
 		return parent::current_action();
 	}
 
+	/**
+	 * Get a list of columns for the list table.
+	 *
+	 * @since  3.1.0
+	 * @access public
+	 *
+	 * @return array Array in which the key is the ID of the column,
+	 *               and the value is the description.
+	 */
 	function get_columns() {
 		$c = array(
 			'cb'       => '<input type="checkbox" />',
@@ -175,6 +264,14 @@ class WP_Users_List_Table extends WP_List_Table {
 		return $c;
 	}
 
+	/**
+	 * Get a list of sortable columns for the list table.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 *
+	 * @return array Array of sortable columns.
+	 */
 	function get_sortable_columns() {
 		$c = array(
 			'username' => 'login',
@@ -188,6 +285,12 @@ class WP_Users_List_Table extends WP_List_Table {
 		return $c;
 	}
 
+	/**
+	 * Generate the list table rows.
+	 *
+	 * @since 3.1.0
+	 * @access public
+	 */
 	function display_rows() {
 		// Query the post counts for this page
 		if ( ! $this->is_site_users )
@@ -216,13 +319,16 @@ class WP_Users_List_Table extends WP_List_Table {
 	/**
 	 * Generate HTML for a single row on the users.php admin panel.
 	 *
-	 * @since 2.1.0
+	 * @since 3.1.0
+	 * @access public
 	 *
-	 * @param object $user_object
+	 * @param object $user_object The current user object.
-	 * @param string $style Optional. Attributes added to the TR element. Must be sanitized.
+	 * @param string $style       Optional. Style attributes added to the <tr> element.
-	 * @param string $role Key for the $wp_roles array.
+	 *                            Must be sanitized. Default empty.
-	 * @param int $numposts Optional. Post count to display for this user. Defaults to zero, as in, a new user has made zero posts.
+	 * @param string $role        Optional. Key for the $wp_roles array. Default empty.
-	 * @return string
+	 * @param int    $numposts    Optional. Post count to display for this user. Defaults
+	 *                            to zero, as in, a new user has made zero posts.
+	 * @return string Output for a single row.
 	 */
 	function single_row( $user_object, $style = '', $role = '', $numposts = 0 ) {
 		global $wp_roles;