[ci skip] Update the Table library docs

1 files changed, 143 insertions, 129 deletions

diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst
index 6a808abc2..25927800e 100644
--- a/user_guide_src/source/libraries/table.rst
+++ b/user_guide_src/source/libraries/table.rst
@@ -5,48 +5,60 @@ HTML Table Class
 The Table Class provides functions that enable you to auto-generate HTML
 tables from arrays or database result sets.
 
+.. content::
+	:local:
+
+.. raw:: html
+
+	<div class="custom-index container"></div>
+
+*********************
+Using the Table Class
+*********************
+
 Initializing the Class
 ======================
 
 Like most other classes in CodeIgniter, the Table class is initialized
-in your controller using the $this->load->library function::
+in your controller using the ``$this->load->library()`` method::
 
 	$this->load->library('table');
 
-Once loaded, the Table library object will be available using:
-$this->table
+Once loaded, the Table library object will be available using::
+
+	$this->table
 
 Examples
 ========
 
 Here is an example showing how you can create a table from a
 multi-dimensional array. Note that the first array index will become the
-table heading (or you can set your own headings using the set_heading()
-function described in the function reference below).
+table heading (or you can set your own headings using the ``set_heading()``
+method described in the function reference below).
 
 ::
 
 	$this->load->library('table');
 
 	$data = array(
-	             array('Name', 'Color', 'Size'),
-	             array('Fred', 'Blue', 'Small'),
-	             array('Mary', 'Red', 'Large'),
-	             array('John', 'Green', 'Medium')	
-	             );
+		array('Name', 'Color', 'Size'),
+		array('Fred', 'Blue', 'Small'),
+		array('Mary', 'Red', 'Large'),
+		array('John', 'Green', 'Medium')	
+	);
 
 	echo $this->table->generate($data);
 
 Here is an example of a table created from a database query result. The
 table class will automatically generate the headings based on the table
-names (or you can set your own headings using the set_heading()
-function described in the function reference below).
+names (or you can set your own headings using the ``set_heading()``
+method described in the class reference below).
 
 ::
 
 	$this->load->library('table');
 
-	$query = $this->db->query("SELECT * FROM my_table");
+	$query = $this->db->query('SELECT * FROM my_table');
 
 	echo $this->table->generate($query);
 
@@ -82,28 +94,28 @@ Changing the Look of Your Table
 The Table Class permits you to set a table template with which you can
 specify the design of your layout. Here is the template prototype::
 
-	$tmpl = array (
-	                    'table_open'          => '<table border="0" cellpadding="4" cellspacing="0">',
+	$template = array(
+		'table_open'          => '<table border="0" cellpadding="4" cellspacing="0">',
 
-	                    'heading_row_start'   => '<tr>',
-	                    'heading_row_end'     => '</tr>',
-	                    'heading_cell_start'  => '<th>',
-	                    'heading_cell_end'    => '</th>',
+		'heading_row_start'   => '<tr>',
+		'heading_row_end'     => '</tr>',
+		'heading_cell_start'  => '<th>',
+		'heading_cell_end'    => '</th>',
 
-	                    'row_start'           => '<tr>',
-	                    'row_end'             => '</tr>',
-	                    'cell_start'          => '<td>',
-	                    'cell_end'            => '</td>',
+		'row_start'           => '<tr>',
+		'row_end'             => '</tr>',
+		'cell_start'          => '<td>',
+		'cell_end'            => '</td>',
 
-	                    'row_alt_start'       => '<tr>',
-	                    'row_alt_end'         => '</tr>',
-	                    'cell_alt_start'      => '<td>',
-	                    'cell_alt_end'        => '</td>',
+		'row_alt_start'       => '<tr>',
+		'row_alt_end'         => '</tr>',
+		'cell_alt_start'      => '<td>',
+		'cell_alt_end'        => '</td>',
 
-	                    'table_close'         => '</table>'
-	              );
+		'table_close'         => '</table>'
+	);
 
-	$this->table->set_template($tmpl);
+	$this->table->set_template($template);
 
 .. note:: You'll notice there are two sets of "row" blocks in the
 	template. These permit you to create alternating row colors or design
@@ -113,157 +125,159 @@ You are NOT required to submit a complete template. If you only need to
 change parts of the layout you can simply submit those elements. In this
 example, only the table opening tag is being changed::
 
-	$tmpl = array ( 'table_open'  => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' );
+	$template = array(
+		'table_open' => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">'
+	);
 
-	$this->table->set_template($tmpl);
+	$this->table->set_template($template);
 	
 You can also set defaults for these in a config file.
 
-******************
-Function Reference
-******************
+***************
+Class Reference
+***************
 
-$this->table->generate()
-========================
+.. class:: CI_Table
 
-Returns a string containing the generated table. Accepts an optional
-parameter which can be an array or a database result object.
+	.. attribute:: $function = FALSE
 
-$this->table->set_caption()
-============================
+		Allows you to specify a native PHP function or a valid function array object to be applied to all cell data.
+		::
 
-Permits you to add a caption to the table.
+			$this->load->library('table');
 
-::
+			$this->table->set_heading('Name', 'Color', 'Size');
+			$this->table->add_row('Fred', '<strong>Blue</strong>', 'Small');
 
-	$this->table->set_caption('Colors');
+			$this->table->function = 'htmlspecialchars';
+			echo $this->table->generate();
 
-$this->table->set_heading()
-============================
+		In the above example, all cell data would be ran through PHP's :php:func:`htmlspecialchars()` function, resulting in::
 
-Permits you to set the table heading. You can submit an array or
-discrete params::
+			<td>Fred</td><td>&lt;strong&gt;Blue&lt;/strong&gt;</td><td>Small</td>
 
-	$this->table->set_heading('Name', 'Color', 'Size');
+	.. method:: generate([$table_data = NULL])
 
-::
+		:param mixed $table_data: data to populate the table rows with
+		:returns: string
 
-	$this->table->set_heading(array('Name', 'Color', 'Size'));
+		Returns a string containing the generated table. Accepts an optional parameter which can be an array or a database result object.
 
-$this->table->add_row()
-========================
+	.. method:: set_caption($caption)
 
-Permits you to add a row to your table. You can submit an array or
-discrete params::
+		:param string $caption: table caption
+		:returns: void
 
-	$this->table->add_row('Blue', 'Red', 'Green');
+		Permits you to add a caption to the table.
+		::
 
-::
+			$this->table->set_caption('Colors');
 
-	$this->table->add_row(array('Blue', 'Red', 'Green'));
+	.. method:: set_heading([$args = array()[, ...]])
 
-If you would like to set an individual cell's tag attributes, you can
-use an associative array for that cell. The associative key 'data'
-defines the cell's data. Any other key => val pairs are added as
-key='val' attributes to the tag::
+		:param mixed $args: an array or multiple strings containing the table column titles
+		:returns: void
 
-	$cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2);
-	$this->table->add_row($cell, 'Red', 'Green');
+		Permits you to set the table heading. You can submit an array or discrete params::
 
-	// generates
-	// <td class='highlight' colspan='2'>Blue</td><td>Red</td><td>Green</td>
+			$this->table->set_heading('Name', 'Color', 'Size');
 
-$this->table->make_columns()
-=============================
+			$this->table->set_heading(array('Name', 'Color', 'Size'));
 
-This function takes a one-dimensional array as input and creates a
-multi-dimensional array with a depth equal to the number of columns
-desired. This allows a single array with many elements to be displayed
-in a table that has a fixed column count. Consider this example::
+	.. method:: add_row([$args = array()[, ...]])
 
-	$list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve');
+		:param mixed $args: an array or multiple strings containing the row values
+		:returns: void
 
-	$new_list = $this->table->make_columns($list, 3);
+		Permits you to add a row to your table. You can submit an array or discrete params::
 
-	$this->table->generate($new_list);
+			$this->table->add_row('Blue', 'Red', 'Green');
 
-	// Generates a table with this prototype
+			$this->table->add_row(array('Blue', 'Red', 'Green'));
 
-	<table border="0" cellpadding="4" cellspacing="0">
-	<tr>
-	<td>one</td><td>two</td><td>three</td>
-	</tr><tr>
-	<td>four</td><td>five</td><td>six</td>
-	</tr><tr>
-	<td>seven</td><td>eight</td><td>nine</td>
-	</tr><tr>
-	<td>ten</td><td>eleven</td><td>twelve</td></tr>
-	</table>
+		If you would like to set an individual cell's tag attributes, you can use an associative array for that cell.
+		The associative key **data** defines the cell's data. Any other key => val pairs are added as key='val' attributes to the tag::
 
-$this->table->set_template()
-=============================
+			$cell = array('data' => 'Blue', 'class' => 'highlight', 'colspan' => 2);
+			$this->table->add_row($cell, 'Red', 'Green');
 
-Permits you to set your template. You can submit a full or partial
-template.
+			// generates
+			// <td class='highlight' colspan='2'>Blue</td><td>Red</td><td>Green</td>
 
-::
+	.. method:: make_columns([$array = array()[, $col_limit = 0]])
 
-	$tmpl = array ( 'table_open'  => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">' );
+		:param array $array: an array containing multiple rows' data
+		:param int $col_limit: count of columns in the table
+		:returns: array
 
-	$this->table->set_template($tmpl);
+		This method takes a one-dimensional array as input and creates a multi-dimensional array with a depth equal to the number of columns desired.
+		This allows a single array with many elements to be displayed in a table that has a fixed column count. Consider this example::
 
-$this->table->set_empty()
-==========================
+			$list = array('one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten', 'eleven', 'twelve');
 
-Let's you set a default value for use in any table cells that are empty.
-You might, for example, set a non-breaking space::
+			$new_list = $this->table->make_columns($list, 3);
 
-	 $this->table->set_empty("&nbsp;");
+			$this->table->generate($new_list);
 
-$this->table->clear()
-=====================
+			// Generates a table with this prototype
 
-Lets you clear the table heading and row data. If you need to show
-multiple tables with different data you should to call this function
-after each table has been generated to empty the previous table
-information. Example::
+			<table border="0" cellpadding="4" cellspacing="0">
+			<tr>
+			<td>one</td><td>two</td><td>three</td>
+			</tr><tr>
+			<td>four</td><td>five</td><td>six</td>
+			</tr><tr>
+			<td>seven</td><td>eight</td><td>nine</td>
+			</tr><tr>
+			<td>ten</td><td>eleven</td><td>twelve</td></tr>
+			</table>
 
-	$this->load->library('table');
 
-	$this->table->set_heading('Name', 'Color', 'Size');
-	$this->table->add_row('Fred', 'Blue', 'Small');
-	$this->table->add_row('Mary', 'Red', 'Large');
-	$this->table->add_row('John', 'Green', 'Medium');
+	.. method:: set_template($template)
 
-	echo $this->table->generate();
+		:param array $template: associative array containing template values
+		:returns: bool
 
-	$this->table->clear();
+		Permits you to set your template. You can submit a full or partial template.
+		::
 
-	$this->table->set_heading('Name', 'Day', 'Delivery');
-	$this->table->add_row('Fred', 'Wednesday', 'Express');
-	$this->table->add_row('Mary', 'Monday', 'Air');
-	$this->table->add_row('John', 'Saturday', 'Overnight');
+		$template = array(
+			'table_open'  => '<table border="1" cellpadding="2" cellspacing="1" class="mytable">'
+		);
 
-	echo $this->table->generate();
+		$this->table->set_template($template);
 
-$this->table->function
-======================
+	.. method:: set_empty($value)
 
-Allows you to specify a native PHP function or a valid function array
-object to be applied to all cell data.
+		:param mixed $value: value to put in empty cells
+		:returns: void
 
-::
+		Lets you set a default value for use in any table cells that are empty.
+		You might, for example, set a non-breaking space::
 
-	$this->load->library('table');
+			$this->table->set_empty("&nbsp;");
 
-	$this->table->set_heading('Name', 'Color', 'Size');
-	$this->table->add_row('Fred', '<strong>Blue</strong>', 'Small');
+	.. method:: clear()
 
-	$this->table->function = 'htmlspecialchars';
-	echo $this->table->generate();
+		:returns: void
+
+		Lets you clear the table heading and row data. If you need to show multiple tables with different data you should to call this method
+		after each table has been generated to clear the previous table information. Example::
+
+			$this->load->library('table');
+
+			$this->table->set_heading('Name', 'Color', 'Size');
+			$this->table->add_row('Fred', 'Blue', 'Small');
+			$this->table->add_row('Mary', 'Red', 'Large');
+			$this->table->add_row('John', 'Green', 'Medium');
+
+			echo $this->table->generate();
 
-In the above example, all cell data would be ran through PHP's
-htmlspecialchars() function, resulting in::
+			$this->table->clear();
 
-	<td>Fred</td><td>&lt;strong&gt;Blue&lt;/strong&gt;</td><td>Small</td>
+			$this->table->set_heading('Name', 'Day', 'Delivery');
+			$this->table->add_row('Fred', 'Wednesday', 'Express');
+			$this->table->add_row('Mary', 'Monday', 'Air');
+			$this->table->add_row('John', 'Saturday', 'Overnight');
 
+			echo $this->table->generate();