[ci skip] DocBlocks for Email, Ftp, Unit_test and Javascript libraries

Partially fixes issue #1295

4 files changed, 437 insertions, 61 deletions

diff --git a/system/libraries/Email.php b/system/libraries/Email.php
index 0109e2890..62f196c05 100644
--- a/system/libraries/Email.php
+++ b/system/libraries/Email.php
@@ -39,55 +39,340 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 class CI_Email {
 
+	/**
+	 * Used as the User-Agent and X-Mailer headers' value.
+	 *
+	 * @var	string
+	 */
 	public $useragent	= 'CodeIgniter';
+
+	/**
+	 * Path to the Sendmail binary.
+	 *
+	 * @var	string
+	 */
 	public $mailpath	= '/usr/sbin/sendmail';	// Sendmail path
+
+	/**
+	 * Which method to use for sending e-mails.
+	 *
+	 * @var	string	'mail', 'sendmail' or 'smtp'
+	 */
 	public $protocol	= 'mail';		// mail/sendmail/smtp
-	public $smtp_host	= '';			// SMTP Server. Example: mail.earthlink.net
-	public $smtp_user	= '';			// SMTP Username
-	public $smtp_pass	= '';			// SMTP Password
-	public $smtp_port	= 25;			// SMTP Port
-	public $smtp_timeout	= 5;			// SMTP Timeout in seconds
-	public $smtp_crypto	= '';			// SMTP Encryption. Can be null, tls or ssl.
-	public $wordwrap	= TRUE;			// TRUE/FALSE - Turns word-wrap on/off
-	public $wrapchars	= 76;			// Number of characters to wrap at.
-	public $mailtype	= 'text';		// text/html - Defines email formatting
-	public $charset		= 'utf-8';		// Default char set: iso-8859-1 or us-ascii
+
+	/**
+	 * STMP Server host
+	 *
+	 * @var	string
+	 */
+	public $smtp_host	= '';
+
+	/**
+	 * SMTP Username
+	 *
+	 * @var	string
+	 */
+	public $smtp_user	= '';
+
+	/**
+	 * SMTP Password
+	 *
+	 * @var	string
+	 */
+	public $smtp_pass	= '';
+
+	/**
+	 * SMTP Server port
+	 *
+	 * @var	int
+	 */
+	public $smtp_port	= 25;
+
+	/**
+	 * SMTP connection timeout in seconds
+	 *
+	 * @var	int
+	 */
+	public $smtp_timeout	= 5;
+
+	/**
+	 * SMTP Encryption
+	 *
+	 * @var	string	NULL, 'tls' or 'ssl'
+	 */
+	public $smtp_crypto	= NULL;
+
+	/**
+	 * Whether to apply word-wrapping to the message body.
+	 *
+	 * @var	bool
+	 */
+	public $wordwrap	= TRUE;
+
+	/**
+	 * Number of characters to wrap at.
+	 *
+	 * @see	CI_Email::$wordwrap
+	 * @var	int
+	 */
+	public $wrapchars	= 76;
+
+	/**
+	 * Message format.
+	 *
+	 * @var	string	'text' or 'html'
+	 */
+	public $mailtype	= 'text';
+
+	/**
+	 * Character set (default: utf-8)
+	 *
+	 * @var	string
+	 */
+	public $charset		= 'utf-8';
+
+	/**
+	 * Multipart message
+	 *
+	 * @var	string	'mixed' (in the body) or 'related' (separate)
+	 */
 	public $multipart	= 'mixed';		// "mixed" (in the body) or "related" (separate)
-	public $alt_message	= '';			// Alternative message for HTML emails
-	public $validate	= FALSE;		// TRUE/FALSE - Enables email validation
+
+	/**
+	 * Alternative message (for HTML messages only)
+	 *
+	 * @var	string
+	 */
+	public $alt_message	= '';
+
+	/**
+	 * Whether to validate e-mail addresses.
+	 *
+	 * @var	bool
+	 */
+	public $validate	= FALSE;
+
+	/**
+	 * X-Priority header value.
+	 *
+	 * @var	int	1-5
+	 */
 	public $priority	= 3;			// Default priority (1 - 5)
+
+	/**
+	 * Newline character sequence.
+	 * Use "\r\n" to comply with RFC 822.
+	 *
+	 * @link	http://www.ietf.org/rfc/rfc822.txt
+	 * @var	string	"\r\n" or "\n"
+	 */
 	public $newline		= "\n";			// Default newline. "\r\n" or "\n" (Use "\r\n" to comply with RFC 822)
-	public $crlf		= "\n";			// The RFC 2045 compliant CRLF for quoted-printable is "\r\n". Apparently some servers,
-									// even on the receiving end think they need to muck with CRLFs, so using "\n", while
-									// distasteful, is the only thing that seems to work for all environments.
-	public $dsn		= FALSE;		// Delivery Status Notification
-	public $send_multipart	= TRUE;		// TRUE/FALSE - Yahoo does not like multipart alternative, so this is an override. Set to FALSE for Yahoo.
-	public $bcc_batch_mode	= FALSE;	// TRUE/FALSE - Turns on/off Bcc batch feature
-	public $bcc_batch_size	= 200;		// If bcc_batch_mode = TRUE, sets max number of Bccs in each batch
 
+	/**
+	 * CRLF character sequence
+	 *
+	 * RFC 2045 specifies that for 'quoted-printable' encoding,
+	 * "\r\n" must be used. However, it appears that some servers
+	 * (even on the receiving end) don't handle it properly and
+	 * switching to "\n", while improper, is the only solution
+	 * that seems to work for all environments.
+	 *
+	 * @link	http://www.ietf.org/rfc/rfc822.txt
+	 * @var	string
+	 */
+	public $crlf		= "\n";
+
+	/**
+	 * Whether to use Delivery Status Notification.
+	 *
+	 * @var	bool
+	 */
+	public $dsn		= FALSE;
+
+	/**
+	 * Whether to send multipart alternatives.
+	 * Yahoo! doesn't seem to like these.
+	 *
+	 * @var	bool
+	 */
+	public $send_multipart	= TRUE;
+
+	/**
+	 * Whether to send messages to BCC recipients in batches.
+	 *
+	 * @var	bool
+	 */
+	public $bcc_batch_mode	= FALSE;
+
+	/**
+	 * BCC Batch max number size.
+	 *
+	 * @see	CI_Email::$bcc_batch_mode
+	 * @var	int
+	 */
+	public $bcc_batch_size	= 200;
+
+	// --------------------------------------------------------------------
+
+	/**
+	 * Whether PHP is running in safe mode. Initialized by the class constructor.
+	 *
+	 * @var	bool
+	 */
 	protected $_safe_mode		= FALSE;
+
+	/**
+	 * Subject header
+	 *
+	 * @var	string
+	 */
 	protected $_subject		= '';
+
+	/**
+	 * Message body
+	 *
+	 * @var	string
+	 */
 	protected $_body		= '';
+
+	/**
+	 * Final message body to be sent.
+	 *
+	 * @var	string
+	 */
 	protected $_finalbody		= '';
+
+	/**
+	 * multipart/alternative boundary
+	 *
+	 * @var	string
+	 */
 	protected $_alt_boundary	= '';
+
+	/**
+	 * Attachment boundary
+	 *
+	 * @var	string
+	 */
 	protected $_atc_boundary	= '';
+
+	/**
+	 * Final headers to send
+	 *
+	 * @var	string
+	 */
 	protected $_header_str		= '';
+
+	/**
+	 * SMTP Connection socket placeholder
+	 *
+	 * @var	resource
+	 */
 	protected $_smtp_connect	= '';
+
+	/**
+	 * Mail encoding
+	 *
+	 * @var	string	'8bit' or '7bit'
+	 */
 	protected $_encoding		= '8bit';
-	protected $_IP			= FALSE;
+
+	/**
+	 * Whether to perform SMTP authentication
+	 *
+	 * @var	bool
+	 */
 	protected $_smtp_auth		= FALSE;
+
+	/**
+	 * Whether to send a Reply-To header
+	 *
+	 * @var	bool
+	 */
 	protected $_replyto_flag	= FALSE;
+
+	/**
+	 * Debug messages
+	 *
+	 * @see	CI_Email::print_debugger()
+	 * @var	string
+	 */
 	protected $_debug_msg		= array();
+
+	/**
+	 * Recipients
+	 *
+	 * @var	string[]
+	 */
 	protected $_recipients		= array();
+
+	/**
+	 * CC Recipients
+	 *
+	 * @var	string[]
+	 */
 	protected $_cc_array		= array();
+
+	/**
+	 * BCC Recipients
+	 *
+	 * @var	string[]
+	 */
 	protected $_bcc_array		= array();
+
+	/**
+	 * Message headers
+	 *
+	 * @var	string[]
+	 */
 	protected $_headers		= array();
+
+	/**
+	 * Attachment data
+	 *
+	 * @var	array
+	 */
 	protected $_attachments		= array();
+
+	/**
+	 * Valid $protocol values
+	 *
+	 * @see	CI_Email::$protocol
+	 * @var	string[]
+	 */
 	protected $_protocols		= array('mail', 'sendmail', 'smtp');
-	protected $_base_charsets	= array('us-ascii', 'iso-2022-');	// 7-bit charsets (excluding language suffix)
+
+	/**
+	 * Base charsets
+	 *
+	 * Character sets valid for 7-bit encoding,
+	 * excluding language suffix.
+	 *
+	 * @var	string[]
+	 */
+	protected $_base_charsets	= array('us-ascii', 'iso-2022-');
+
+	/**
+	 * Bit depths
+	 *
+	 * Valid mail encodings
+	 *
+	 * @see	CI_Email::$_encoding
+	 * @var	string[]
+	 */
 	protected $_bit_depths		= array('7bit', '8bit');
+
+	/**
+	 * $priority translations
+	 *
+	 * Actual values to send with the X-Priority header
+	 *
+	 * @var	string[]
+	 */
 	protected $_priorities		= array('1 (Highest)', '2 (High)', '3 (Normal)', '4 (Low)', '5 (Lowest)');
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor - Sets Email Preferences
 	 *
diff --git a/system/libraries/Ftp.php b/system/libraries/Ftp.php
index b9954c7f2..60c03b5ad 100644
--- a/system/libraries/Ftp.php
+++ b/system/libraries/Ftp.php
@@ -37,18 +37,63 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 class CI_FTP {
 
+	/**
+	 * FTP Server hostname
+	 *
+	 * @var	string
+	 */
 	public $hostname	= '';
+
+	/**
+	 * FTP Username
+	 *
+	 * @var	string
+	 */
 	public $username	= '';
+
+	/**
+	 * FTP Password
+	 *
+	 * @var	string
+	 */
 	public $password	= '';
+
+	/**
+	 * FTP Server port
+	 *
+	 * @var	int
+	 */
 	public $port		= 21;
+
+	/**
+	 * Passive mode flag
+	 *
+	 * @var	bool
+	 */
 	public $passive		= TRUE;
+
+	/**
+	 * Debug flag
+	 *
+	 * Specifies whether to display error messages.
+	 *
+	 * @var	bool
+	 */
 	public $debug		= FALSE;
+
+	/**
+	 * Connection
+	 *
+	 * @var	resource
+	 */
 	public $conn_id		= FALSE;
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor
 	 *
-	 * @param	array	$config = array()
+	 * @param	array	$config
 	 * @return	void
 	 */
 	public function __construct($config = array())
@@ -66,7 +111,7 @@ class CI_FTP {
 	/**
 	 * Initialize preferences
 	 *
-	 * @param	array
+	 * @param	array	$config
 	 * @return	void
 	 */
 	public function initialize($config = array())
@@ -88,7 +133,7 @@ class CI_FTP {
 	/**
 	 * FTP Connect
 	 *
-	 * @param	array	 the connection values
+	 * @param	array	 $config	Connection values
 	 * @return	bool
 	 */
 	public function connect($config = array())
@@ -168,8 +213,8 @@ class CI_FTP {
 	 * so we do it by trying to change to a particular directory.
 	 * Internally, this parameter is only used by the "mirror" function below.
 	 *
-	 * @param	string
-	 * @param	bool
+	 * @param	string	$path
+	 * @param	bool	$supress_debug
 	 * @return	bool
 	 */
 	public function changedir($path = '', $supress_debug = FALSE)
@@ -198,8 +243,8 @@ class CI_FTP {
 	/**
 	 * Create a directory
 	 *
-	 * @param	string
-	 * @param	int
+	 * @param	string	$path
+	 * @param	int	$permissions
 	 * @return	bool
 	 */
 	public function mkdir($path = '', $permissions = NULL)
@@ -234,10 +279,10 @@ class CI_FTP {
 	/**
 	 * Upload a file to the server
 	 *
-	 * @param	string
-	 * @param	string
-	 * @param	string
-	 * @param	int
+	 * @param	string	$locpath
+	 * @param	string	$rempath
+	 * @param	string	$mode
+	 * @param	int	$permissions
 	 * @return	bool
 	 */
 	public function upload($locpath, $rempath, $mode = 'auto', $permissions = NULL)
@@ -288,9 +333,9 @@ class CI_FTP {
 	/**
 	 * Download a file from a remote server to the local server
 	 *
-	 * @param	string
-	 * @param	string
-	 * @param	string
+	 * @param	string	$rempath
+	 * @param	string	$locpath
+	 * @param	string	$mode
 	 * @return	bool
 	 */
 	public function download($rempath, $locpath, $mode = 'auto')
@@ -329,9 +374,9 @@ class CI_FTP {
 	/**
 	 * Rename (or move) a file
 	 *
-	 * @param	string
-	 * @param	string
-	 * @param	bool
+	 * @param	string	$old_file
+	 * @param	string	$new_file
+	 * @param	bool	$move
 	 * @return	bool
 	 */
 	public function rename($old_file, $new_file, $move = FALSE)
@@ -360,8 +405,8 @@ class CI_FTP {
 	/**
 	 * Move a file
 	 *
-	 * @param	string
-	 * @param	string
+	 * @param	string	$old_file
+	 * @param	string	$new_file
 	 * @return	bool
 	 */
 	public function move($old_file, $new_file)
@@ -374,7 +419,7 @@ class CI_FTP {
 	/**
 	 * Rename (or move) a file
 	 *
-	 * @param	string
+	 * @param	string	$filepath
 	 * @return	bool
 	 */
 	public function delete_file($filepath)
@@ -404,7 +449,7 @@ class CI_FTP {
 	 * Delete a folder and recursively delete everything (including sub-folders)
 	 * containted within it.
 	 *
-	 * @param	string
+	 * @param	string	$filepath
 	 * @return	bool
 	 */
 	public function delete_dir($filepath)
@@ -451,8 +496,8 @@ class CI_FTP {
 	/**
 	 * Set file permissions
 	 *
-	 * @param	string	the file path
-	 * @param	int	the permissions
+	 * @param	string	$path	File path
+	 * @param	int	$perm	Permissions
 	 * @return	bool
 	 */
 	public function chmod($path, $perm)
@@ -481,7 +526,7 @@ class CI_FTP {
 	/**
 	 * FTP List files in the specified directory
 	 *
-	 * @param	string	$path = '.'
+	 * @param	string	$path
 	 * @return	array
 	 */
 	public function list_files($path = '.')
@@ -504,8 +549,8 @@ class CI_FTP {
 	 * Whatever the directory structure of the original file path will be
 	 * recreated on the server.
 	 *
-	 * @param	string	path to source with trailing slash
-	 * @param	string	path to destination - include the base folder with trailing slash
+	 * @param	string	$locpath	Path to source with trailing slash
+	 * @param	string	$rempath	Path to destination - include the base folder with trailing slash
 	 * @return	bool
 	 */
 	public function mirror($locpath, $rempath)
@@ -551,7 +596,7 @@ class CI_FTP {
 	/**
 	 * Extract the file extension
 	 *
-	 * @param	string
+	 * @param	string	$filename
 	 * @return	string
 	 */
 	protected function _getext($filename)
@@ -570,7 +615,7 @@ class CI_FTP {
 	/**
 	 * Set the upload type
 	 *
-	 * @param	string
+	 * @param	string	$ext	Filename extension
 	 * @return	string
 	 */
 	protected function _settype($ext)
@@ -617,7 +662,7 @@ class CI_FTP {
 	/**
 	 * Display error message
 	 *
-	 * @param	string
+	 * @param	string	$line
 	 * @return	void
 	 */
 	protected function _error($line)
diff --git a/system/libraries/Javascript.php b/system/libraries/Javascript.php
index c2f458de8..9a15cddaa 100644
--- a/system/libraries/Javascript.php
+++ b/system/libraries/Javascript.php
@@ -37,12 +37,19 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 class CI_Javascript {
 
+	/**
+	 * JavaScript location
+	 *
+	 * @var	string
+	 */
 	protected $_javascript_location = 'js';
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor
 	 *
-	 * @param	array	$params = array()
+	 * @param	array	$params
 	 * @return	void
 	 */
 	public function __construct($params = array())
@@ -587,8 +594,8 @@ class CI_Javascript {
 	 *
 	 * gather together all script needing to be output
 	 *
-	 * @param	string	$view_var = 'script_foot'
-	 * @param	bool	$script_tags = TRUE
+	 * @param	string	$view_var
+	 * @param	bool	$script_tags
 	 * @return	string
 	 */
 	public function compile($view_var = 'script_foot', $script_tags = TRUE)
@@ -617,8 +624,8 @@ class CI_Javascript {
 	 *
 	 * Outputs a <script> tag with the source as an external js file
 	 *
-	 * @param	string	$external_file = ''
-	 * @param	bool	$relative = FALSE
+	 * @param	string	$external_file
+	 * @param	bool	$relative
 	 * @return	string
 	 */
 	public function external($external_file = '', $relative = FALSE)
diff --git a/system/libraries/Unit_test.php b/system/libraries/Unit_test.php
index 5c0018d35..2710b5513 100644
--- a/system/libraries/Unit_test.php
+++ b/system/libraries/Unit_test.php
@@ -39,13 +39,52 @@ defined('BASEPATH') OR exit('No direct script access allowed');
  */
 class CI_Unit_test {
 
+	/**
+	 * Active flag
+	 *
+	 * @var	bool
+	 */
 	public $active			= TRUE;
+
+	/**
+	 * Test results
+	 *
+	 * @var	array
+	 */
 	public $results			= array();
+
+	/**
+	 * Strict comparison flag
+	 *
+	 * Whether to use === or == when comparing
+	 *
+	 * @var	bool
+	 */
 	public $strict			= FALSE;
+
+	/**
+	 * Template
+	 *
+	 * @var	string
+	 */
 	protected $_template		= NULL;
+
+	/**
+	 * Template rows
+	 *
+	 * @var	string
+	 */
 	protected $_template_rows	= NULL;
+
+	/**
+	 * List of visible test items
+	 *
+	 * @var	array
+	 */
 	protected $_test_items_visible	= array();
 
+	// --------------------------------------------------------------------
+
 	/**
 	 * Constructor
 	 *
@@ -93,9 +132,9 @@ class CI_Unit_test {
 	 * Runs the supplied tests
 	 *
 	 * @param	mixed	$test
-	 * @param	mixed	$expected = TRUE
-	 * @param	string	$test_name = 'undefined'
-	 * @param	string	$notes = ''
+	 * @param	mixed	$expected
+	 * @param	string	$test_name
+	 * @param	string	$notes
 	 * @return	string
 	 */
 	public function run($test, $expected = TRUE, $test_name = 'undefined', $notes = '')
@@ -113,7 +152,7 @@ class CI_Unit_test {
 		}
 		else
 		{
-			$result = ($this->strict === TRUE) ? ($test === $expected) : ($test === $expected);
+			$result = ($this->strict === TRUE) ? ($test === $expected) : ($test == $expected);
 			$extype = gettype($expected);
 		}
 
@@ -141,7 +180,7 @@ class CI_Unit_test {
 	 *
 	 * Displays a table with the test data
 	 *
-	 * @param	array	 $result = array()
+	 * @param	array	 $result
 	 * @return	string
 	 */
 	public function report($result = array())
@@ -221,7 +260,7 @@ class CI_Unit_test {
 	 *
 	 * Returns the raw result data
 	 *
-	 * @param	array	$results = array()
+	 * @param	array	$results
 	 * @return	array
 	 */
 	public function result($results = array())