Polish the Common functions documentation

2 files changed, 124 insertions, 36 deletions

diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 27fc975b5..77af73323 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -273,12 +273,12 @@ Release Date: Not Released
 	 -  Changed internal method ``_sanitize_globals()`` to skip enforcing reversal of *register_globals* in PHP 5.4+, where this functionality no longer exists.
 	 -  Changed methods ``get()``, ``post()``, ``get_post()``, ``cookie()``, ``server()``, ``user_agent()`` to return NULL instead of FALSE when no value is found.
    -  :doc:`Common functions <general/common_functions>` changes include:
-	 -  Added function ``get_mimes()`` to return the *config/mimes.php* array.
-	 -  Added support for HTTP code 303 ("See Other") in ``set_status_header()``.
-	 -  Removed redundant conditional to determine HTTP server protocol in ``set_status_header()``.
+	 -  Added function :php:func:`get_mimes()` to return the *application/config/mimes.php* array.
+	 -  Added support for HTTP code 303 ("See Other") in :php:func:`set_status_header()`.
+	 -  Removed redundant conditional to determine HTTP server protocol in :php:func:`set_status_header()`.
 	 -  Changed ``_exception_handler()`` to respect php.ini *display_errors* setting.
-	 -  Added function ``is_https()`` to check if a secure connection is used.
-	 -  Added function ``function_usable()`` to check if a function exists and is not disabled by `Suhosin <http://www.hardened-php.net/suhosin/>`.
+	 -  Added function :php:func:`is_https()` to check if a secure connection is used.
+	 -  Added function :php:func:`function_usable()` to check if a function exists and is not disabled by `Suhosin <http://www.hardened-php.net/suhosin/>`.
    -  Added support for HTTP-Only cookies with new config option *cookie_httponly* (default FALSE).
    -  Renamed method ``_call_hook()`` to ``call_hook()`` in the :doc:`Hooks Library <general/hooks>`.
    -  :doc:`Output Library <libraries/output>` changes include:
diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst
index 22f8d1942..66dabd95e 100644
--- a/user_guide_src/source/general/common_functions.rst
+++ b/user_guide_src/source/general/common_functions.rst
@@ -6,45 +6,62 @@ CodeIgniter uses a few functions for its operation that are globally
 defined, and are available to you at any point. These do not require
 loading any libraries or helpers.
 
-is_php('version_number')
-========================
+is_php()
+========
 
-is_php() determines of the PHP version being used is greater than the
-supplied version_number.
+.. php:function:: is_php($version = '5.3.0')
 
-::
+	:param	string	$version: Version number
+	:returns:	bool
 
-	if (is_php('5.3.0'))
+Determines of the PHP version being used is greater than the
+supplied version number.
+
+Example::
+
+	if (is_php('5.3'))
 	{
-	    $str = quoted_printable_encode($str);
+		$str = quoted_printable_encode($str);
 	}
 
 Returns boolean TRUE if the installed version of PHP is equal to or
 greater than the supplied version number. Returns FALSE if the installed
 version of PHP is lower than the supplied version number.
 
-is_really_writable('path/to/file')
-==================================
+is_really_writable()
+====================
+
+.. php:function:: is_really_writeable($file)
 
-is_writable() returns TRUE on Windows servers when you really can't
+	:param	string	$file: File path
+	:returns:	bool
+
+``is_writable()`` returns TRUE on Windows servers when you really can't
 write to the file as the OS reports to PHP as FALSE only if the
-read-only attribute is marked. This function determines if a file is
-actually writable by attempting to write to it first. Generally only
-recommended on platforms where this information may be unreliable.
+read-only attribute is marked.
+
+This function determines if a file is actually writable by attempting
+to write to it first. Generally only recommended on platforms where
+this information may be unreliable.
 
-::
+Example::
 
 	if (is_really_writable('file.txt'))
 	{
-	    echo "I could write to this if I wanted to";
+		echo "I could write to this if I wanted to";
 	}
 	else
 	{
-	    echo "File is not writable";
+		echo "File is not writable";
 	}
 
-config_item('item_key')
-=======================
+config_item()
+=============
+
+.. php:function:: config_item($key)
+
+	:param	string	$key: Config item key
+	:returns:	mixed
 
 The :doc:`Config Library <../libraries/config>` is the preferred way of
 accessing configuration information, however ``config_item()`` can be used
@@ -55,14 +72,53 @@ documentation for more information.
 	files. It does not take into account config values that are
 	dynamically set at runtime.
 
-show_error('message'), show_404('page'), log_message('level', 'message')
-========================================================================
+show_error()
+============
+
+.. php:function:: show_error($message, $status_code, $heading = 'An Error Was Encountered')
+
+	:param	mixed	$message: Error message
+	:param	int	$status_code: HTTP Response status code
+	:param	string	$heading: Error page heading
+	:returns:	void
+
+This function calls ``CI_Exception::show_error()``. For more info,
+please see the :doc:`Error Handling <errors>` documentation.
+
+show_404()
+==========
+
+.. php:function:: show_404($page = '', $log_error = TRUE)
+
+	:param	string	$page: URI string
+	:param	bool	$log_error: Whether to log the error
+	:returns:	void
+
+This function calls ``CI_Exception::show_404()``. For more info,
+please see the :doc:`Error Handling <errors>` documentation.
+
+log_message()
+=============
+
+.. php:function:: log_message($level = 'error', $message, $php_error = FALSE)
 
-These are each outlined on the :doc:`Error Handling <errors>` page.
+	:param	string	$level: Log level
+	:param	string	$message: Message to log
+	:param	bool	$php_error: Whether we're loggin a native PHP error message
+	:returns:	void
 
-set_status_header(code, 'text')
+This function is an alias for ``CI_Log::write_log()``. For more info,
+please see the :doc:`Error Handling <errors>` documentation.
+
+set_status_header()
 ===============================
 
+.. php:function:: set_status_header($code, $text = '')
+
+	:param	int	$code: HTTP Reponse status code
+	:param	string	$text: A custom message to set with the status code
+	:returns:	void
+
 Permits you to manually set a server status header. Example::
 
 	set_status_header(401);
@@ -71,33 +127,65 @@ Permits you to manually set a server status header. Example::
 `See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for
 a full list of headers.
 
-remove_invisible_characters($str)
-=================================
+remove_invisible_characters()
+=============================
+
+.. php:function:: remove_invisible_characters($str, $url_encoded = TRUE)
 
-This function prevents inserting null characters between ascii
+	:param	string	$str: Input string
+	:param	bool	$url_encoded: Whether to remove URL-encoded characters as well
+	:returns:	string
+
+This function prevents inserting NULL characters between ASCII
 characters, like Java\\0script.
 
-html_escape($mixed)
-===================
+Example::
+
+	remove_invisible_characters('Java\\0script');
+	// Returns: 'Javascript'
+
+html_escape()
+=============
+
+.. php:function:: html_escape($var)
 
-This function provides short cut for ``htmlspecialchars()`` function. It
-accepts string and array. To prevent Cross Site Scripting (XSS), it is
-very useful.
+	:param	mixed	$var: Variable to escape
+			(string or array)
+	:returns:	mixed
+
+This function acts as an alias for PHP's native ``htmlspecialchars()``
+function, with the advantage of being able to accept an array of strings.
+
+It is useful in preventing Cross Site Scripting (XSS).
 
 get_mimes()
 ===========
 
-This function returns the MIMEs array *from config/mimes.php*.
+.. php:function:: get_mimes()
+
+	:returns:	array
+
+This function returns a *reference* to the MIMEs array from
+*application/config/mimes.php*.
 
 is_https()
 ==========
 
+.. php:function:: is_https()
+
+	:returns:	bool
+
 Returns TRUE if a secure (HTTPS) connection is used and FALSE
 in any other case (including non-HTTP requests).
 
 function_usable($function_name)
 ===============================
 
+.. php:function:: function_usable($function_name)
+
+	:param	string	$function_name: Function name
+	:returns:	bool
+
 Returns TRUE if a function exists and is usable, FALSE otherwise.
 
 This function runs a ``function_exists()`` check and if the