[ci skip] Update the Security class docs

1 files changed, 60 insertions, 43 deletions

diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst
index 05553142f..3d0697bbe 100644
--- a/user_guide_src/source/libraries/security.rst
+++ b/user_guide_src/source/libraries/security.rst
@@ -23,12 +23,7 @@ Note: This function should only be used to deal with data upon
 submission. It's not something that should be used for general runtime
 processing since it requires a fair amount of processing overhead.
 
-To filter data through the XSS filter use this function:
-
-$this->security->xss_clean()
-============================
-
-Here is an usage example::
+To filter data through the XSS filter use the ``xss_clean()`` method::
 
 	$data = $this->security->xss_clean($data);
 
@@ -38,10 +33,10 @@ application/config/config.php file and setting this::
 
 	$config['global_xss_filtering'] = TRUE;
 
-Note: If you use the form validation class, it gives you the option of
-XSS filtering as well.
+.. note:: If you use the form validation class, it gives you the option of
+	XSS filtering as well.
 
-An optional second parameter, is_image, allows this function to be used
+An optional second parameter, *is_image*, allows this function to be used
 to test images for potential XSS attacks, useful for file upload
 security. When this second parameter is set to TRUE, instead of
 returning an altered string, the function returns TRUE if the image is
@@ -52,40 +47,20 @@ browser may attempt to execute.
 
 	if ($this->security->xss_clean($file, TRUE) === FALSE)
 	{
-	    // file failed the XSS test
+		// file failed the XSS test
 	}
 
-$this->security->sanitize_filename()
-====================================
-
-When accepting filenames from user input, it is best to sanitize them to
-prevent directory traversal and other security related issues. To do so,
-use the sanitize_filename() method of the Security class. Here is an
-example::
-
-	$filename = $this->security->sanitize_filename($this->input->post('filename'));
-
-If it is acceptable for the user input to include relative paths, e.g.
-file/in/some/approved/folder.txt, you can set the second optional
-parameter, $relative_path to TRUE.
-
-::
-
-	$filename = $this->security->sanitize_filename($this->input->post('filename'), TRUE);
-
 Cross-site request forgery (CSRF)
 =================================
 
-You can enable CSRF protection by opening your
-application/config/config.php file and setting this::
+You can enable CSRF protection by altering your **application/config/config.php**
+file in the following way::
 
 	$config['csrf_protection'] = TRUE;
 
 If you use the :doc:`form helper <../helpers/form_helper>`, then
-``form_open()`` will automatically insert a hidden csrf field in
-your forms. If not, then you can use ``csrf_get_token_name()``
-and ``csrf_get_hash()``
-
+:func:`form_open()` will automatically insert a hidden csrf field in
+your forms. If not, then you can use ``csrf_get_token_name()`` and ``csrf_get_hash()``
 ::
 
 	$csrf = array(
@@ -114,15 +89,57 @@ by editing the 'csrf_exclude_uris' config parameter::
 
 	$config['csrf_exclude_uris'] = array('api/person/add');
 
-$this->security->get_csrf_token_name()
-======================================
+***************
+Class Reference
+***************
+
+.. class:: CI_Security
+
+	.. method:: xss_clean($str[, $is_image = FALSE])
+
+		:param string $str: Input string
+		:returns: mixed
+
+		Tries to remove XSS exploits from the input data and returns the cleaned string.
+		If the optional second parameter is set to true, it will return boolean TRUE if the image is safe to use and FALSE if malicious data was detected in it.
+
+	.. method:: sanitize_filename($str[, $relative_path = FALSE])
+
+		:param string $str: File name/path
+		:param bool $relative_path: Whether to preserve any directories in the file path
+		:returns: string
+
+		Tries to sanitize filenames in order to prevent directory traversal attempts
+		and other security threats, which is particularly useful for files that were supplied via user input.
+		::
+
+			$filename = $this->security->sanitize_filename($this->input->post('filename'));
+
+		If it is acceptable for the user input to include relative paths, e.g.
+		*file/in/some/approved/folder.txt*, you can set the second optional parameter, ``$relative_path`` to TRUE.
+		::
+
+			$filename = $this->security->sanitize_filename($this->input->post('filename'), TRUE);
+
+	.. method:: get_csrf_token_name()
+
+		:returns: string
+
+		Returns the CSRF token name (the ``$config['csrf_token_name']`` value).
+
+	.. method:: get_csrf_hash()
+
+		:returns: string
+
+		Returns the CSRF hash value. Useful in combination with ``get_csrf_token_name()``
+		for manually building forms or sending valid AJAX POST requests.
+
+	.. method:: entity_decode($str[, $charset = NULL])
 
-Returns the CSRF token name, which is set by
-``$config['csrf_token_name']``.
+		:param string $str: Input string
+		:param string $charset: Character set of the input string
 
-$this->security->get_csrf_hash()
-================================
+		This method acts a lot like PHP's own native ``html_entity_decode()`` function in ENT_COMPAT mode, only
+		it tries to detect HTML entities that don't end in a semicolon because some browsers allow that.
 
-Returns the CSRF hash value. Useful in combination with
-``get_csrf_token_name()`` for manually building forms or 
-sending valid AJAX POST requests.
\ No newline at end of file
+		If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used.
\ No newline at end of file