inline doc improvements in WP_Filesystem_Direct and WP_List_Table

[bananastalktome]

A pass over WP_Filesystem_Direct and WP_List_Table classes to improve inline docs. Any suggestions/improvements/critiques are welcomed.

[kitchin]

I suggest this at Line 576 in wp-admin/includes/class-wp-list-table.php

 	 * Get a list of sortable columns. The format is:
 	 * 'internal-name' => 'orderby'
 	 * or
+	 * 'internal-name' => array( 'orderby', false )
+	 * or
 	 * 'internal-name' => array( 'orderby', true )
 	 *
-	 * The second format will make the initial sorting order be descending
+	 * The third format will make the initial sorting order be descending.
+	 *
+	 * If your class explicitly sets $this->_column_headers,
+	 * note the first format is invalid in print_column_headers().
 	 *
 	 * @since 3.1.0
 	 * @access protected
	 *
	 * @return array
	 */
	function get_sortable_columns() {
		return array();
	}

The problem with the first format is that print_column_headers() expects an array at line 686:

list( $orderby, $desc_first ) = $sortable[$column_key];

The first format is OK when it is rolled into an array by get_column_info(), but if you set _column_headers explicitly, then get_column_info() is bypassed. This is the approach taken by the API example plugin ​http://wordpress.org/extend/plugins/custom-list-table-example/ , which does use the correct second format.

[dd32]

In 25560:

First pass at documenting the WP_Filesystem methods. This also introduces stubs of the methods into the base class which are documented, which subclasses can override, some methods were cleaned up at the same time.
See #18476 See #23122. Props kurtpayne, bananastalktome, and, DrewAPicture

[nacin]

New tickets for more patches, I guess. Closing as fixed for 3.7.