[ci skip] Router class DocBlock improvements

2 files changed, 120 insertions, 103 deletions

diff --git a/system/core/Output.php b/system/core/Output.php
index aa0e05dc4..3f2f84fa1 100644
--- a/system/core/Output.php
+++ b/system/core/Output.php
@@ -28,7 +28,7 @@
 /**
  * Output Class
  *
- * Responsible for sending final output to browser
+ * Responsible for sending final output to the browser.
  *
  * @package		CodeIgniter
  * @subpackage	Libraries
@@ -39,70 +39,74 @@
 class CI_Output {
 
 	/**
-	 * Current output string
+	 * Final output string
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	public $final_output;
 
 	/**
 	 * Cache expiration time
 	 *
-	 * @var int
+	 * @var	int
 	 */
-	public $cache_expiration =	0;
+	public $cache_expiration = 0;
 
 	/**
 	 * List of server headers
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	public $headers =	array();
 
 	/**
 	 * List of mime types
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	public $mimes =		array();
 
 	/**
 	 * Mime-type for the current page
 	 *
-	 * @var string
+	 * @var	string
 	 */
-	protected $mime_type		= 'text/html';
+	protected $mime_type	= 'text/html';
 
 	/**
-	 * Determines whether profiler is enabled
+	 * Enable Profiler flag
 	 *
-	 * @var book
+	 * @var	bool
 	 */
-	public $enable_profiler =	FALSE;
+	public $enable_profiler = FALSE;
 
 	/**
-	 * Determines if output compression is enabled
+	 * zLib output compression flag
 	 *
-	 * @var bool
+	 * @var	bool
 	 */
 	protected $_zlib_oc =		FALSE;
 
 	/**
 	 * List of profiler sections
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	protected $_profiler_sections =	array();
 
 	/**
-	 * Whether or not to parse variables like {elapsed_time} and {memory_usage}
+	 * Parse markers flag
 	 *
-	 * @var bool
+	 * Whether or not to parse variables like {elapsed_time} and {memory_usage}.
+	 *
+	 * @var	bool
 	 */
 	public $parse_exec_vars =	TRUE;
 
 	/**
-	 * Set up Output class
+	 * Class constructor
+	 *
+	 * Determines whether zLib output compression will be used.
 	 *
 	 * @return	void
 	 */
@@ -121,7 +125,7 @@ class CI_Output {
 	/**
 	 * Get Output
 	 *
-	 * Returns the current output string
+	 * Returns the current output string.
 	 *
 	 * @return	string
 	 */
@@ -135,10 +139,10 @@ class CI_Output {
 	/**
 	 * Set Output
 	 *
-	 * Sets the output string
+	 * Sets the output string.
 	 *
-	 * @param	string
-	 * @return	void
+	 * @param	string	$output	Output data
+	 * @return	object	$this
 	 */
 	public function set_output($output)
 	{
@@ -151,14 +155,14 @@ class CI_Output {
 	/**
 	 * Append Output
 	 *
-	 * Appends data onto the output string
+	 * Appends data onto the output string.
 	 *
-	 * @param	string
-	 * @return	void
+	 * @param	string	$output	Data to append
+	 * @return	object	$this
 	 */
 	public function append_output($output)
 	{
-		if ($this->final_output == '')
+		if (empty($this->final_output))
 		{
 			$this->final_output = $output;
 		}
@@ -175,16 +179,16 @@ class CI_Output {
 	/**
 	 * Set Header
 	 *
-	 * Lets you set a server header which will be outputted with the final display.
+	 * Lets you set a server header which will be sent with the final output.
 	 *
-	 * Note: If a file is cached, headers will not be sent. We need to figure out
-	 * how to permit header data to be saved with the cache data...
+	 * Note: If a file is cached, headers will not be sent.
+	 * @todo	We need to figure out how to permit headers to be cached.
 	 *
-	 * @param	string
-	 * @param	bool
-	 * @return	void
+	 * @param	string	$header		Header
+	 * @param	bool	$replace	Whether to replace the old header value, if already set
+	 * @return	object	$this
 	 */
-	public function set_header($header, $replace = TRUE)
+	public function set_header($header, $replace)
 	{
 		// If zlib.output_compression is enabled it will compress the output,
 		// but it will not modify the content-length header to compensate for
@@ -192,7 +196,7 @@ class CI_Output {
 		// We'll just skip content-length in those cases.
 		if ($this->_zlib_oc && strncasecmp($header, 'content-length', 14) === 0)
 		{
-			return;
+			return $this;
 		}
 
 		$this->headers[] = array($header, $replace);
@@ -202,11 +206,11 @@ class CI_Output {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set Content Type Header
+	 * Set Content-Type Header
 	 *
-	 * @param	string	$mime_type	extension of the file we're outputting
-	 * @param	string	$charset = NULL
-	 * @return	void
+	 * @param	string	$mime_type	Extension of the file we're outputting
+	 * @param	string	$charset	Character set (default: NULL)
+	 * @return	object	$this
 	 */
 	public function set_content_type($mime_type, $charset = NULL)
 	{
@@ -243,7 +247,7 @@ class CI_Output {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Get Current Content Type Header
+	 * Get Current Content-Type Header
 	 *
 	 * @return	string	'text/html', if not already set
 	 */
@@ -264,11 +268,13 @@ class CI_Output {
 
 	/**
 	 * Set HTTP Status Header
-	 * moved to Common procedural functions in 1.7.2
 	 *
-	 * @param	int	the status code
-	 * @param	string
-	 * @return	void
+	 * As of version 1.7.2, this is an alias for common function
+	 * set_status_header().
+	 *
+	 * @param	int	$code	Status code (default: 200)
+	 * @param	string	$text	Optional message
+	 * @return	object	$this
 	 */
 	public function set_status_header($code = 200, $text = '')
 	{
@@ -281,8 +287,8 @@ class CI_Output {
 	/**
 	 * Enable/disable Profiler
 	 *
-	 * @param	bool
-	 * @return	void
+	 * @param	bool	$val	TRUE to enable or FALSE to disable
+	 * @return	object	$this
 	 */
 	public function enable_profiler($val = TRUE)
 	{
@@ -295,10 +301,11 @@ class CI_Output {
 	/**
 	 * Set Profiler Sections
 	 *
-	 * Allows override of default / config settings for Profiler section display
+	 * Allows override of default/config settings for
+	 * Profiler section display.
 	 *
-	 * @param	array
-	 * @return	void
+	 * @param	array	$sections	Profiler sections
+	 * @return	object	$this
 	 */
 	public function set_profiler_sections($sections)
 	{
@@ -321,8 +328,8 @@ class CI_Output {
 	/**
 	 * Set Cache
 	 *
-	 * @param	int
-	 * @return	void
+	 * @param	int	$time	Cache expiration time in seconds
+	 * @return	object	$this
 	 */
 	public function cache($time)
 	{
@@ -335,16 +342,16 @@ class CI_Output {
 	/**
 	 * Display Output
 	 *
-	 * All "view" data is automatically put into this variable by the controller class:
-	 *
-	 * $this->final_output
+	 * Processes sends the sends finalized output data to the browser along
+	 * with any server headers and profile data. It also stops benchmark
+	 * timers so the page rendering speed and memory usage can be shown.
 	 *
-	 * This function sends the finalized output data to the browser along
-	 * with any server headers and profile data. It also stops the
-	 * benchmark timer so the page rendering speed and memory usage can be shown.
+	 * Note: All "view" data is automatically put into $this->final_output
+	 *	 by controller class.
 	 *
-	 * @param	string
-	 * @return	mixed
+	 * @uses	CI_Output::$final_output
+	 * @param	string	$output	Output data override
+	 * @return	void
 	 */
 	public function _display($output = '')
 	{
@@ -431,7 +438,7 @@ class CI_Output {
 			echo $output;
 			log_message('debug', 'Final output sent to browser');
 			log_message('debug', 'Total execution time: '.$elapsed);
-			return TRUE;
+			return;
 		}
 
 		// --------------------------------------------------------------------
@@ -473,9 +480,9 @@ class CI_Output {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Write a Cache File
+	 * Write Cache
 	 *
-	 * @param	string
+	 * @param	string	$output	Output data to cache
 	 * @return	void
 	 */
 	public function _write_cache($output)
@@ -526,11 +533,14 @@ class CI_Output {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Update/serve a cached file
+	 * Update/serve cached output
 	 *
-	 * @param	object	config class
-	 * @param	object	uri class
-	 * @return	bool
+	 * @uses	CI_Config
+	 * @uses	CI_URI
+	 *
+	 * @param	object	&$CFG	CI_Config class instance
+	 * @param	object	&$URI	CI_URI class instance
+	 * @return	bool	TRUE on success or FALSE on failure
 	 */
 	public function _display_cache(&$CFG, &$URI)
 	{
@@ -584,11 +594,13 @@ class CI_Output {
 	// --------------------------------------------------------------------
 
 	/**
+	 * Set Cache Header
+	 *
 	 * Set the HTTP headers to match the server-side file cache settings
 	 * in order to reduce bandwidth.
 	 *
-	 * @param	int	timestamp of when the page was last modified
-	 * @param	int	timestamp of when should the requested page expire from cache
+	 * @param	int	$last_modified	Timestamp of when the page was last modified
+	 * @param	int	$expiration	Timestamp of when should the requested page expire from cache
 	 * @return	void
 	 */
 	public function set_cache_header($last_modified, $expiration)
@@ -612,11 +624,13 @@ class CI_Output {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Reduce excessive size of HTML content.
+	 * Minify
 	 *
-	 * @param	string
-	 * @param	string
-	 * @return	string
+	 * Reduce excessive size of HTML/CSS/JavaScript content.
+	 *
+	 * @param	string	$output	Output to minify
+	 * @param	string	$type	Output content MIME type
+	 * @return	string	Minified output
 	 */
 	public function minify($output, $type = 'text/html')
 	{
diff --git a/system/core/Router.php b/system/core/Router.php
index 5bc053045..efee2439f 100644
--- a/system/core/Router.php
+++ b/system/core/Router.php
@@ -39,56 +39,56 @@
 class CI_Router {
 
 	/**
-	 * Config class
+	 * CI_Config class object
 	 *
-	 * @var object
+	 * @var	object
 	 */
 	public $config;
 
 	/**
 	 * List of routes
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	public $routes =	array();
 
 	/**
 	 * List of error routes
 	 *
-	 * @var array
+	 * @var	array
 	 */
 	public $error_routes =	array();
 
 	/**
 	 * Current class name
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	public $class =		'';
 
 	/**
 	 * Current method name
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	public $method =	'index';
 
 	/**
 	 * Sub-directory that contains the requested controller class
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	public $directory =	'';
 
 	/**
 	 * Default controller (and method if specific)
 	 *
-	 * @var string
+	 * @var	string
 	 */
 	public $default_controller;
 
 	/**
-	 * Constructor
+	 * Class constructor
 	 *
 	 * Runs the route mapping function.
 	 *
@@ -104,9 +104,9 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the route mapping
+	 * Set route mapping
 	 *
-	 * This function determines what should be served based on the URI request,
+	 * Determines what should be served based on the URI request,
 	 * as well as any "routes" that have been set in the routing config file.
 	 *
 	 * @return	void
@@ -179,7 +179,7 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the default controller
+	 * Set default controller
 	 *
 	 * @return	void
 	 */
@@ -213,12 +213,12 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the Route
+	 * Set request route
 	 *
-	 * This function takes an array of URI segments as
-	 * input, and sets the current class/method
+	 * Takes an array of URI segments as input and sets the class/method
+	 * to be called.
 	 *
-	 * @param	array
+	 * @param	array	$segments	URI segments
 	 * @return	void
 	 */
 	protected function _set_request($segments = array())
@@ -253,11 +253,12 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Validates the supplied segments.
-	 * Attempts to determine the path to the controller.
+	 * Validate request
 	 *
-	 * @param	array
-	 * @return	array
+	 * Attempts validate the URI request and determine the controller path.
+	 *
+	 * @param	array	$segments	URI segments
+	 * @return	array	URI segments
 	 */
 	protected function _validate_request($segments)
 	{
@@ -347,9 +348,8 @@ class CI_Router {
 	/**
 	 * Parse Routes
 	 *
-	 * This function matches any routes that may exist in
-	 * the config/routes.php file against the URI to
-	 * determine if the class/method need to be remapped.
+	 * Matches any routes that may exist in the config/routes.php file
+	 * against the URI to determine if the class/method need to be remapped.
 	 *
 	 * @return	void
 	 */
@@ -391,9 +391,9 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the class name
+	 * Set class name
 	 *
-	 * @param	string
+	 * @param	string	$class	Class name
 	 * @return	void
 	 */
 	public function set_class($class)
@@ -416,9 +416,9 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the method name
+	 * Set method name
 	 *
-	 * @param	string
+	 * @param	string	$method	Method name
 	 * @return	void
 	 */
 	public function set_method($method)
@@ -441,9 +441,9 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the directory name
+	 * Set directory name
 	 *
-	 * @param	string
+	 * @param	string	$dir	Directory name
 	 * @return	void
 	 */
 	public function set_directory($dir)
@@ -454,7 +454,10 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Fetch the sub-directory (if any) that contains the requested controller class
+	 * Fetch directory
+	 *
+	 * Feches the sub-directory (if any) that contains the requested
+	 * controller class.
 	 *
 	 * @return	string
 	 */
@@ -466,9 +469,9 @@ class CI_Router {
 	// --------------------------------------------------------------------
 
 	/**
-	 * Set the controller overrides
+	 * Set controller overrides
 	 *
-	 * @param	array
+	 * @param	array	$routing	Route overrides
 	 * @return	void
 	 */
 	public function _set_overrides($routing)