Changeset 27301

Timestamp:

02/26/2014 10:19:10 PM (11 years ago)

Author:

DrewAPicture

Message:

Improve inline documentation for WP_Users_List_Table.

Props leewillis77 for the initial patch.
Fixes #26564.

File:

• trunk/src/wp-admin/includes/class-wp-users-list-table.php (modified) (11 diffs)

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

@@ -3 +3 @@
  * Users List Table class.
  *
+ * @since 3.1.0
+ * @access private
+ *
  * @package WordPress
  * @subpackage List_Table
- * @since 3.1.0
- * @access private
  */
 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(
@@ -26 +48 @@
     }
 
+    /**
+     * Check the current user's permissions.
+     *
+     * @since 3.1.0
+     * @access public
+     */
     function ajax_user_can() {
         if ( $this->is_site_users )
@@ -33 +61 @@
     }
 
+    /**
+     * Prepare the users list for display.
+     *
+     * @since 3.1.0
+     * @access public
+     */
     function prepare_items() {
         global $role, $usersearch;
@@ -76 +110 @@
     }
 
+    /**
+     * 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;
@@ -120 +172 @@
     }
 
+    /**
+     * 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();
@@ -134 +194 @@
     }
 
+    /**
+     * 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 )
@@ -153 +222 @@
     }
 
+    /**
+     * 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']) )
@@ -160 +240 @@
     }
 
+    /**
+     * 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(
@@ -176 +265 @@
     }
 
+    /**
+     * 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(
@@ -189 +286 @@
     }
 
+    /**
+     * Generate the list table rows.
+     *
+     * @since 3.1.0
+     * @access public
+     */
     function display_rows() {
         // Query the post counts for this page
@@ -217 +320 @@
      * Generate HTML for a single row on the users.php admin panel.
      *
-     * @since 2.1.0
-     *
-     * @param object $user_object
-     * @param string $style Optional. Attributes added to the TR element. Must be sanitized.
-     * @param string $role Key for the $wp_roles array.
-     * @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
+     * @since 3.1.0
+     * @access public
+     *
+     * @param object $user_object The current user object.
+     * @param string $style       Optional. Style attributes added to the <tr> element.
+     *                            Must be sanitized. Default empty.
+     * @param string $role        Optional. Key for the $wp_roles array. 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.
+     * @return string Output for a single row.
      */
     function single_row( $user_object, $style = '', $role = '', $numposts = 0 ) {