diff options
| author | Andrey Andreev <narf@devilix.net> | 2014-02-08 03:27:48 +0100 |
|---|---|---|
| committer | Andrey Andreev <narf@devilix.net> | 2014-02-08 03:27:48 +0100 |
| commit | 28c2c975b118016d07212ed8e7c22ff280309f82 (patch) | |
| tree | f1552392a3d87efebd7c565c6414ae41dc208ee9 /user_guide_src | |
| parent | 9228f85b1b4f59cc88ba7c4addc258a7a5fd0ac0 (diff) | |
[ci skip] Add return types to library docs
Diffstat (limited to 'user_guide_src')
28 files changed, 836 insertions, 666 deletions
diff --git a/user_guide_src/source/libraries/benchmark.rst b/user_guide_src/source/libraries/benchmark.rst index 7a0313f43..ddbe04869 100644 --- a/user_guide_src/source/libraries/benchmark.rst +++ b/user_guide_src/source/libraries/benchmark.rst @@ -135,18 +135,18 @@ Class Reference .. method:: mark($name) - :param string $name: the name you wish to assign to your marker - :returns: void + :param string $name: the name you wish to assign to your marker + :rtype: void Sets a benchmark marker. - .. method:: elapsed_time([$point1 = ''[, $point2 = ''[, $decimals = 4]]]) - :param string $point1: a particular marked point - :param string $point2: a particular marked point - :param int $decimals: number of decimal places for precision - :returns: string + :param string $point1: a particular marked point + :param string $point2: a particular marked point + :param int $decimals: number of decimal places for precision + :returns: Elapsed time + :rtype: string Calculates and returns the time difference between two marked points. @@ -158,7 +158,8 @@ Class Reference .. method:: memory_usage() - :returns: string + :returns: Memory usage info + :rtype: string Simply returns the ``{memory_usage}`` marker. diff --git a/user_guide_src/source/libraries/caching.rst b/user_guide_src/source/libraries/caching.rst index 30a9fed2d..caece1aee 100644 --- a/user_guide_src/source/libraries/caching.rst +++ b/user_guide_src/source/libraries/caching.rst @@ -56,8 +56,9 @@ Class Reference .. method:: is_supported($driver) - :param string $driver: the name of the caching driver - :returns: TRUE if supported, FALSE if not + :param string $driver: the name of the caching driver + :returns: TRUE if supported, FALSE if not + :rtype: bool This method is automatically called when accessing drivers via ``$this->cache->get()``. However, if the individual drivers are used, @@ -75,8 +76,9 @@ Class Reference .. method:: get($id) - :param string $id: name of cached item - :returns: The item if it exists, FALSE if it does not + :param string $id: Cache item name + :returns: Item value or FALSE if not found + :rtype: mixed This method will attempt to fetch an item from the cache store. If the item does not exist, the method will return FALSE. @@ -86,11 +88,12 @@ Class Reference .. method:: save($id, $data[, $ttl = 60[, $raw = FALSE]]) - :param string $id: name of the cached item - :param mixed $data: the data to save - :param int $ttl: Time To Live, in seconds (default 60) - :param bool $raw: Whether to store the raw value - :returns: TRUE on success, FALSE on failure + :param string $id: Cache item name + :param mixed $data: the data to save + :param int $ttl: Time To Live, in seconds (default 60) + :param bool $raw: Whether to store the raw value + :returns: TRUE on success, FALSE on failure + :rtype: string This method will save an item to the cache store. If saving fails, the method will return FALSE. @@ -103,8 +106,9 @@ Class Reference .. method:: delete($id) - :param string $id: name of cached item - :returns: TRUE if deleted, FALSE if the deletion fails + :param string $id: name of cached item + :returns: TRUE on success, FALSE on failure + :rtype: bool This method will delete a specific item from the cache store. If item deletion fails, the method will return FALSE. @@ -114,9 +118,10 @@ Class Reference .. method:: increment($id[, $offset = 1]) - :param string $id: Cache ID - :param int $offset: Step/value to add - :returns: New value on success, FALSE on failure + :param string $id: Cache ID + :param int $offset: Step/value to add + :returns: New value on success, FALSE on failure + :rtype: mixed Performs atomic incrementation of a raw stored value. :: @@ -129,9 +134,10 @@ Class Reference .. method:: decrement($id[, $offset = 1]) - :param string $id: Cache ID - :param int $offset: Step/value to reduce by - :returns: New value on success, FALSE on failure + :param string $id: Cache ID + :param int $offset: Step/value to reduce by + :returns: New value on success, FALSE on failure + :rtype: mixed Performs atomic decrementation of a raw stored value. :: @@ -144,7 +150,8 @@ Class Reference .. method:: clean() - :returns: TRUE if deleted, FALSE if the deletion fails + :returns: TRUE on success, FALSE on failure + :rtype: bool This method will 'clean' the entire cache. If the deletion of the cache files fails, the method will return FALSE. @@ -154,7 +161,8 @@ Class Reference .. method:: cache_info() - :returns: information on the entire cache + :returns: Information on the entire cache database + :rtype: mixed This method will return information on the entire cache. :: @@ -166,8 +174,9 @@ Class Reference .. method:: get_metadata($id) - :param string $id: name of cached item - :returns: metadadta for the cached item + :param string $id: Cache item name + :returns: Metadata for the cached item + :rtype: mixed This method will return detailed information on a specific item in the cache. diff --git a/user_guide_src/source/libraries/calendar.rst b/user_guide_src/source/libraries/calendar.rst index 3879672ce..aa10e941d 100644 --- a/user_guide_src/source/libraries/calendar.rst +++ b/user_guide_src/source/libraries/calendar.rst @@ -201,48 +201,49 @@ Class Reference .. method:: initialize([$config = array()]) - :param array $config: config preferences - :returns: void + :param array $config: Configuration parameters + :rtype: void Initializes the Calendaring preferences. Accepts an associative array as input, containing display preferences. - .. method:: generate([$year = ''[, $month = ''[, $data = array()]]]) - :param int $year: the year - :param int $month: the month - :param array $data: the data to be shown in the calendar cells - :returns: string + :param int $year: Year + :param int $month: Month + :param array $data: Data to be shown in the calendar cells + :returns: HTML-formatted calendar + :rtype: string Generate the calendar. .. method:: get_month_name($month) - :param int $month: the numeric month - :returns: string + :param int $month: Month + :returns: Month name + :rtype: string Generates a textual month name based on the numeric month provided. - .. method:: get_day_names($day_type = '') - :param string $day_type: one of 'long', 'short', or 'abr' - :returns: array + :param string $day_type: 'long', 'short', or 'abr' + :returns: Array of day names + :rtype: array Returns an array of day names (Sunday, Monday, etc.) based on the type provided. Options: long, short, abr. If no ``$day_type`` is provided (or if an invalid type is provided) this method will return the "abbreviated" style. - .. method:: adjust_date($month, $year) - :param int $month: the month - :param int $year: the year - :returns: array + :param int $month: Month + :param int $year: Year + :returns: An associative array containing month and year + :rtype: array - This method makes usre that you have a valid month/year. For example, if + This method makes sure that you have a valid month/year. For example, if you submit 13 as the month, the year will increment and the month will become January:: @@ -256,22 +257,22 @@ Class Reference [year] => '2014' ) - .. method:: get_total_days($month, $year) - :param int $month: the month - :param int $year: the year - :returns: int + :param int $month: Month + :param int $year: Year + :returns: Count of days in the specified month + :rtype: int Total days in a given month:: echo $this->calendar->get_total_days(2, 2012); // 29 - .. method:: default_template() - :returns: array + :returns: An array of template values + :rtype: array Sets the default template. This method is used when you have not created your own template. @@ -279,7 +280,7 @@ Class Reference .. method:: parse_template() - :returns: void + :rtype: void Harvests the data within the template ``{pseudo-variables}`` used to display the calendar.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/cart.rst b/user_guide_src/source/libraries/cart.rst index 0c8c0a601..fb92c280a 100644 --- a/user_guide_src/source/libraries/cart.rst +++ b/user_guide_src/source/libraries/cart.rst @@ -275,8 +275,9 @@ Class Reference .. method:: insert([$items = array()]) - :param array $items: the items to insert into the cart - :returns: bool + :param array $items: Items to insert into the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool Insert items into the cart and save it to the session table. Returns TRUE on success and FALSE on failure. @@ -284,83 +285,85 @@ Class Reference .. method:: update([$items = array()]) - :param array $items: the items to update in the cart - :returns: bool + :param array $items: Items to update in the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool This method permits the quantity of a given item to be changed. Typically it is called from the "view cart" page if a user makes changes to the quantity before checkout. That array must contain the product ID and quantity for each item. - .. method:: remove($rowid) - :param int $rowid: the ID of the item to remove from the cart - :returns: bool + :param int $rowid: ID of the item to remove from the cart + :returns: TRUE on success, FALSE on failure + :rtype: bool Allows you to remove an item from the shopping cart by passing it the ``$rowid``. - .. method:: total() - :returns: int + :returns: Total amount + :rtype: int Displays the total amount in the cart. .. method:: total_items() - :returns: int + :returns: Total amount of items in the cart + :rtype: int Displays the total number of items in the cart. .. method:: contents([$newest_first = FALSE]) - :param bool $newest_first: order the array with newest first? - :returns: array + :param bool $newest_first: Whether to order the array with newest items first + :returns: An array of cart contents + :rtype: array Returns an array containing everything in the cart. You can sort the order by which the array is returned by passing it TRUE where the contents will be sorted from newest to oldest, otherwise it is sorted from oldest to newest. - .. method:: get_item($row_id) - :param int $row_id: the row ID to retrieve - :returns: array + :param int $row_id: Row ID to retrieve + :returns: Array of item data + :rtype: array Returns an array containing data for the item matching the specified row ID, or FALSE if no such item exists. - .. method:: has_options($row_id = '') - :param int $row_id: the row ID to inspect - :returns: bool + :param int $row_id: Row ID to inspect + :returns: TRUE if options exist, FALSE otherwise + :rtype: bool Returns TRUE (boolean) if a particular row in the cart contains options. - This method is designed to be used in a loop with :meth:contents:, since + This method is designed to be used in a loop with ``contents()``, since you must pass the rowid to this function, as shown in the Displaying the Cart example above. - .. method:: product_options([$row_id = '']) - :param int $row_id: the row ID - :returns: array + :param int $row_id: Row ID + :returns: Array of product options + :rtype: array Returns an array of options for a particular product. This method is - designed to be used in a loop with :meth:contents:, since you + designed to be used in a loop with ``contents()``, since you must pass the rowid to this method, as shown in the Displaying the Cart example above. - .. method:: destroy() - :returns: void + :rtype: void Permits you to destroy the cart. This method will likely be called when you are finished processing the customer's order.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/config.rst b/user_guide_src/source/libraries/config.rst index 8663324f2..b31815799 100644 --- a/user_guide_src/source/libraries/config.rst +++ b/user_guide_src/source/libraries/config.rst @@ -184,47 +184,44 @@ Class Reference .. method:: item($item[, $index='']) - :param string $item: config item name - :param string $index: index name, if the item is an element in a config - item that is itself an array. - :returns: mixed - the config item or FALSE if it does not exist + :param string $item: Config item name + :param string $index: Index name + :returns: Config item value or NULL if not found + :rtype: mixed Fetch a config file item. - .. method:: set_item($item, $value) - :param string $item: config item name - :param string $value: config item value - :returns: void + :param string $item: Config item name + :param string $value: Config item value + :rtype: void Sets a config file item to the specified value. - .. method:: slash_item($item) - :param string $item: config item name - :returns: moxied - the config item (slashed) or FALSE if it does not exist + :param string $item: config item name + :returns: Config item value with a trailing forward slash or NULL if not found + :rtype: mixed - This method is identical to :meth:item:, except it appends a forward + This method is identical to ``item()``, except it appends a forward slash to the end of the item, if it exists. - .. method:: load([$file = ''[, $use_sections = FALSE[, $fail_gracefully = FALSE]]]) - :param string $file: Configuration file name - :param bool $use_sections: Whether config values shoud be loaded into - their own section (index of the main config array) - :param bool $fail_gracefully: Whether to return FALSE or to display an - error message - :returns: bool + :param string $file: Configuration file name + :param bool $use_sections: Whether config values shoud be loaded into their own section (index of the main config array) + :param bool $fail_gracefully: Whether to return FALSE or to display an error message + :returns: TRUE on success, FALSE on failure + :rtype: bool Loads a configuration file. - .. method:: site_url() - :returns: string + :returns: Site URL + :rtype: string This method retrieves the URL to your site, along with the "index" value you've specified in the config file. @@ -232,10 +229,10 @@ Class Reference This method is normally accessed via the corresponding functions in the :doc:`URL Helper </helpers/url_helper>`. - .. method:: base_url() - :returns: string + :returns: Base URL + :rtype: string This method retrieves the URL to your site, plus an optional path such as to a stylesheet or image. @@ -243,9 +240,9 @@ Class Reference This method is normally accessed via the corresponding functions in the :doc:`URL Helper </helpers/url_helper>`. - .. method:: system_url() - :returns: string + :returns: URL pointing at your CI system/ directory + :rtype: string - This method retrieves the URL to your system folder. + This method retrieves the URL to your CodeIgniter system/ directory.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index ec639846f..3f990b628 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -145,10 +145,11 @@ Class Reference .. method:: from($from[, $name = ''[, $return_path = NULL]]) - :param string $from: "From" email address - :param string $name: "From" display name - :param string $return_path: optional email address to redirect undelivered email - :returns: CI_Email object for method chaining + :param string $from: "From" e-mail address + :param string $name: "From" display name + :param string $return_path: Optional email address to redirect undelivered e-mail to + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Sets the email address and name of the person sending the email:: @@ -161,26 +162,26 @@ Class Reference .. note:: Return-Path can't be used if you've configured 'smtp' as your protocol. - .. method:: reply_to($replyto[, $name = '']) - :param string $replyto: email address for replies - :param string $name: display name for reply email address - :returns: CI_Email object for method chaining + :param string $replyto: E-mail address for replies + :param string $name: Display name for the reply-to e-mail address + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Sets the reply-to address. If the information is not provided the information in the :meth:from method is used. Example:: $this->email->reply_to('you@example.com', 'Your Name'); - .. method:: to($to) - :param mixed $to: comma delimited string or array of email addresses - :returns: CI_Email object for method chaining + :param mixed $to: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the email address(s) of the recipient(s). Can be a single email - , a comma-delimited list or an array:: + Sets the email address(s) of the recipient(s). Can be a single e-mail, + a comma-delimited list or an array:: $this->email->to('someone@example.com'); @@ -190,60 +191,60 @@ Class Reference :: - $list = array('one@example.com', 'two@example.com', 'three@example.com'); - - $this->email->to($list); - + $this->email->to( + array('one@example.com', 'two@example.com', 'three@example.com') + ); .. method:: cc($cc) - :param mixed $cc: comma delimited string or array of email addresses - :returns: CI_Email object for method chaining - - Sets the CC email address(s). Just like the "to", can be a single - email, a comma-delimited list or an array. + :param mixed $cc: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email + Sets the CC email address(s). Just like the "to", can be a single e-mail, + a comma-delimited list or an array. - .. method:: bcc($bcc, $limit = '') + .. method:: bcc($bcc[, $limit = '']) - :param mixed $bcc: comma delimited string or array of email addresses - :param int $limit: Maximum number of emails to send per batch - :returns: CI_Email object for method chaining + :param mixed $bcc: Comma-delimited string or an array of e-mail addresses + :param int $limit: Maximum number of e-mails to send per batch + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the BCC email address(s). Just like the "to", can be a single - email, a comma-delimited list or an array. + Sets the BCC email address(s). Just like the ``to()`` method, can be a single + e-mail, a comma-delimited list or an array. If ``$limit`` is set, "batch mode" will be enabled, which will send the emails to batches, with each batch not exceeding the specified ``$limit``. - .. method:: subject($subject) - :param string $subject: email subject line - :returns: CI_Email object for method chaining + :param string $subject: E-mail subject line + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Sets the email subject:: $this->email->subject('This is my subject'); - .. method:: message($body) - :param string $body: email body - :returns: CI_Email object for method chaining + :param string $body: E-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the email message body:: + Sets the e-mail message body:: $this->email->message('This is my message'); - .. method:: set_alt_message([$str = '']) - :param string $str: alternate email body - :returns: CI_Email object for method chaining + :param string $str: Alternative e-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - Sets the alternative email message body:: + Sets the alternative e-mail message body:: $this->email->set_alt_message('This is the alternative message'); @@ -256,19 +257,21 @@ Class Reference .. method:: set_header($header, $value) - :param string $header: header name - :param string $value: header value - :returns: void + :param string $header: Header name + :param string $value: Header value + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Appends additional headers to the e-mail:: $this->email->set_header('Header1', 'Value1'); $this->email->set_header('Header2', 'Value2'); - .. method:: clear([$clear_attachments = FALSE]) - :param bool $clear_attachments: whether or not to clear attachments + :param bool $clear_attachments: Whether or not to clear attachments + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Initializes all the email variables to an empty state. This method is intended for use if you run the email sending method in a loop, @@ -292,13 +295,13 @@ Class Reference $this->email->clear(TRUE); - .. method:: send([$auto_clear = TRUE]) - :param bool $auto_clear: Whether to :meth:clear automatically - :returns: bool + :param bool $auto_clear: Whether to clear message data automatically + :returns: TRUE on success, FALSE on failure + :rtype: bool - The Email sending method. Returns boolean TRUE or FALSE based on + The e-mail sending method. Returns boolean TRUE or FALSE based on success or failure, enabling it to be used conditionally:: if ( ! $this->email->send()) @@ -317,16 +320,16 @@ Class Reference .. note:: In order to use the ``print_debugger()`` method, you need to avoid clearing the email parameters. - .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) - :param string $filename: name of the file - :param string $disposition: 'disposition' of the attachment. Most + :param string $filename: File name + :param string $disposition: 'disposition' of the attachment. Most email clients make their own decision regardless of the MIME specification used here. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml - :param string $newname: custom name to use for the file in the email - :param string $mime: MIME type to use (useful for buffered data) - :returns: CI_Email object for method chaining + :param string $newname: Custom file name to use in the e-mail + :param string $mime: MIME type to use (useful for buffered data) + :returns: CI_Email instance (method chaining) + :rtype: CI_Email Enables you to send an attachment. Put the file path/name in the first parameter. For multiple attachments use the method multiple times. @@ -357,8 +360,9 @@ Class Reference .. method:: attachment_cid($filename) - :param string $filename: Existing attachment filename - :returns: string + :param string $filename: Existing attachment filename + :returns: Attachment Content-ID or FALSE if not found + :rtype: string Sets and returns an attachment's Content-ID, which enables your to embed an inline (picture) attachment into HTML. First parameter must be the already attached file name. @@ -378,8 +382,9 @@ Class Reference .. method:: print_debugger([$include = array('headers', 'subject', 'body')]) - :param array $include: Which parts of the message to print out - :returns: string + :param array $include: Which parts of the message to print out + :returns: Formatted debug data + :rtype: string Returns a string containing any server messages, the email headers, and the email messsage. Useful for debugging. diff --git a/user_guide_src/source/libraries/encryption.rst b/user_guide_src/source/libraries/encryption.rst index f7235bfd2..567a1e990 100644 --- a/user_guide_src/source/libraries/encryption.rst +++ b/user_guide_src/source/libraries/encryption.rst @@ -81,11 +81,12 @@ Class Reference .. class:: CI_Encrypt - .. method:: encode($string, $key = '') + .. method:: encode($string[, $key = '']) - :param string $string: contents to be encrypted - :param string $key: encryption key - :returns: string + :param string $string: Data to encrypt + :param string $key: Encryption key + :returns: Encrypted string + :rtype: string Performs the data encryption and returns it as a string. Example:: @@ -101,12 +102,12 @@ Class Reference $encrypted_string = $this->encrypt->encode($msg, $key); + .. method:: decode($string[, $key = '']) - .. method:: decode($string, $key = '') - - :param string $string: contents to be decrypted - :param string $key: encryption key - :returns: string + :param string $string: String to decrypt + :param string $key: Encryption key + :returns: Plain-text string + :rtype: string Decrypts an encoded string. Example:: @@ -122,46 +123,44 @@ Class Reference $encrypted_string = $this->encrypt->decode($msg, $key); - .. method:: set_cipher($cipher) - :param int $cipher: valid PHP Mcrypt cypher constant - :returns: CI_Encrypt object for method chaining + :param int $cipher: Valid PHP MCrypt cypher constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt Permits you to set an Mcrypt cipher. By default it uses - **MCRYPT_RIJNDAEL_256**. Example:: + ``MCRYPT_RIJNDAEL_256``. Example:: $this->encrypt->set_cipher(MCRYPT_BLOWFISH); - Please visit php.net for a list of `available - ciphers <http://php.net/mcrypt>`_. + Please visit php.net for a list of `available ciphers <http://php.net/mcrypt>`_. - If you'd like to manually test whether your server supports Mcrypt you + If you'd like to manually test whether your server supports MCrypt you can use:: - echo ( ! function_exists('mcrypt_encrypt')) ? 'Nope' : 'Yup'; - + echo extension_loaded('mcrypt') ? 'Yup' : 'Nope'; .. method:: set_mode($mode) - :param int $mode: valid PHP Mcrypt mode constant - :returns: CI_Encrypt object for method chaining + :param int $mode: Valid PHP MCrypt mode constant + :returns: CI_Encrypt instance (method chaining) + :rtype: CI_Encrypt Permits you to set an Mcrypt mode. By default it uses **MCRYPT_MODE_CBC**. Example:: $this->encrypt->set_mode(MCRYPT_MODE_CFB); - Please visit php.net for a list of `available - modes <http://php.net/mcrypt>`_. - + Please visit php.net for a list of `available modes <http://php.net/mcrypt>`_. .. method:: encode_from_legacy($string[, $legacy_mode = MCRYPT_MODE_ECB[, $key = '']]) - :param string $string: contents to be encrypted - :param int $legacy_mode: valid PHP Mcrypt cypher constant - :param string $key: encryption key - :returns: string + :param string $string: String to encrypt + :param int $legacy_mode: Valid PHP MCrypt cipher constant + :param string $key: Encryption key + :returns: Newly encrypted string + :rtype: string Enables you to re-encode data that was originally encrypted with CodeIgniter 1.x to be compatible with the Encryption library in diff --git a/user_guide_src/source/libraries/file_uploading.rst b/user_guide_src/source/libraries/file_uploading.rst index d679d8aa2..d7ba3a6c1 100644 --- a/user_guide_src/source/libraries/file_uploading.rst +++ b/user_guide_src/source/libraries/file_uploading.rst @@ -256,8 +256,9 @@ Class Reference .. method:: do_upload([$field = 'userfile']) - :param string $field: name of the form field - :returns: bool + :param string $field: Name of the form field + :returns: TRUE on success, FALSE on failure + :rtype: bool Performs the upload based on the preferences you've set. @@ -275,12 +276,12 @@ Class Reference $field_name = "some_field_name"; $this->upload->do_upload($field_name); - .. method:: display_errors([$open = '<p>'[, $close = '</p>']]) - :param string $open: Opening markup - :param string $close: Closing markup - :returns: string + :param string $open: Opening markup + :param string $close: Closing markup + :returns: Formatted error message(s) + :rtype: string Retrieves any error messages if the ``do_upload()`` method returned false. The method does not echo automatically, it returns the data so @@ -296,8 +297,9 @@ Class Reference .. method:: data([$index = NULL]) - :param string $data: element to return instead of the full array - :returns: mixed + :param string $data: Element to return instead of the full array + :returns: Information about the uploaded file + :rtype: mixed This is a helper method that returns an array containing all of the data related to the file you uploaded. Here is the array prototype:: @@ -324,25 +326,23 @@ Class Reference $this->upload->data('file_name'); // Returns: mypic.jpg - **Explanation** - - Here is an explanation of the above array items. - - ================ ================================================ - Item Description - ================ ================================================ - file_name The name of the file that was uploaded including the file extension. - file_type The file's Mime type - file_path The absolute server path to the file - full_path The absolute server path including the file name - raw_name The file name without the extension - orig_name The original file name. This is only useful if you use the encrypted name option. - client_name The file name as supplied by the client user agent, prior to any file name preparation or incrementing. - file_ext The file extension with period - file_size The file size in kilobytes - is_image Whether the file is an image or not. 1 = image. 0 = not. - image_width Image width. - image_height Image height - image_type Image type. Typically the file extension without the period. - image_size_str A string containing the width and height. Useful to put into an image tag. - ================ ================================================ + Here's a table explaining the above-displayed array items: + + ================ ==================================================================================================== + Item Description + ================ ==================================================================================================== + file_name Name of the file that was uploaded, including the filename extension + file_type File MIME type identifier + file_path Absolute server path to the file + full_path Absolute server path, including the file name + raw_name File name, without the extension + orig_name Original file name. This is only useful if you use the encrypted name option. + client_name File name as supplied by the client user agent, prior to any file name preparation or incrementing + file_ext Filename extension, period included + file_size File size in kilobytes + is_image Whether the file is an image or not. 1 = image. 0 = not. + image_width Image width + image_height Image height + image_type Image type (usually the file name extension without the period) + image_size_str A string containing the width and height (useful to put into an image tag) + ================ ====================================================================================================
\ No newline at end of file diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst index 42422f9d7..ae66cefb3 100644 --- a/user_guide_src/source/libraries/form_validation.rst +++ b/user_guide_src/source/libraries/form_validation.rst @@ -958,10 +958,11 @@ Class Reference .. method:: set_rules($field[, $label = ''[, $rules = '']]) - :param string $field: The field name - :param string $label: The field label - :param mixed $rules: The rules, as a string with rules separated by a pipe "|", or an array or rules. - :returns: object + :param string $field: Field name + :param string $label: Field label + :param mixed $rules: Validation rules, as a string list separated by a pipe "|", or as an array or rules + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Permits you to set validation rules, as described in the tutorial sections above: @@ -971,8 +972,9 @@ Class Reference .. method:: run([$group = '']) - :param string $group: The name of the validation group to run - :returns: bool + :param string $group: The name of the validation group to run + :returns: TRUE on success, FALSE if validation failed + :rtype: bool Runs the validation routines. Returns boolean TRUE on success and FALSE on failure. You can optionally pass the name of the validation group via @@ -980,64 +982,70 @@ Class Reference .. method:: set_message($lang[, $val = '']) - :param string $lang: The rule the message is for - :param string $val: The message - :returns: object + :param string $lang: The rule the message is for + :param string $val: The message + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Permits you to set custom error messages. See :ref:`setting-error-messages` .. method:: set_error_delimiters([$prefix = '<p>'[, $suffix = '</p>']]) - :param string $prefix: Error message prefix - :param string $suffix: Error message suffix - :returns: object + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: CI_Form_validation instance (method chaining) + :rtype: CI_Form_validation Sets the default prefix and suffix for error messages. .. method:: set_data($data) - :param array $data: The data to validate - :returns: void + :param array $data: Array of data validate + :rtype: void Permits you to set an array for validation, instead of using the default ``$_POST`` array. .. method:: reset_validation() - :returns: void + :rtype: void Permits you to reset the validation when you validate more than one array. This method should be called before validating each new array. .. method:: error_array() - :returns: array + :returns: Array of error messages + :rtype: array Returns the error messages as an array. .. method:: error_string([$prefix = ''[, $suffix = '']]) - :param string $prefix: Error message prefix - :param string $suffix: Error message suffix - :returns: string + :param string $prefix: Error message prefix + :param string $suffix: Error message suffix + :returns: Error messages as a string + :rtype: string Returns all error messages (as returned from error_array()) formatted as a string and separated by a newline character. .. method:: error($field[, $prefix = ''[, $suffix = '']]) - :param string $field: Field name - :param string $prefix: Optional prefix - :param string $suffix: Optional suffix - :returns: string + :param string $field: Field name + :param string $prefix: Optional prefix + :param string $suffix: Optional suffix + :returns: Error message string + :rtype: string Returns the error message for a specific field, optionally adding a prefix and/or suffix to it (usually HTML tags). .. method:: has_rule($field) - :param string $field: Field name - :returns: bool + :param string $field: Field name + :returns: TRUE if the field has rules set, FALSE if not + :rtype: bool Checks to see if there is a rule set for the specified field. diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index c587869db..dd9440443 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -94,8 +94,9 @@ Class Reference .. method:: connect([$config = array()]) - :param array $config: Connection values - :returns: bool + :param array $config: Connection values + :returns: TRUE on success, FALSE on failure + :rtype: bool Connects and logs into to the FTP server. Connection preferences are set by passing an array to the function, or you can store them in a config @@ -123,24 +124,25 @@ Class Reference **Available connection options** - ================== =================================== - Option Name Description - ================== =================================== - **hostname** the FTP hostname. Usually something like: ftp.example.com - **username** the FTP username - **password** the FTP password - **port** The port number. Set to 21 by default. - **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. - **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. - ================== =================================== + ============== =============== ============================================================================= + Option name Default value Description + ============== =============== ============================================================================= + **hostname** n/a FTP hostname (usually something like: ftp.example.com) + **username** n/a FTP username + **password** n/a FTP password + **port** 21 FTP server port number + **debug** FALSE TRUE/FALSE (boolean): Whether to enable debugging to display error messages + **passive** TRUE TRUE/FALSE (boolean): Whether to use passive mode + ============== =============== ============================================================================= .. method:: upload($locpath, $rempath[, $mode = 'auto'[, $permissions = NULL]]) - :param string $locpath: Local file path - :param string $rempath: Remote file path - :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') - :param int $permissions: File permissions (octal) - :returns: bool + :param string $locpath: Local file path + :param string $rempath: Remote file path + :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') + :param int $permissions: File permissions (octal) + :returns: TRUE on success, FALSE on failure + :rtype: bool Uploads a file to your server. You must supply the local path and the remote path, and you can optionally set the mode and permissions. @@ -154,10 +156,11 @@ Class Reference .. method:: download($rempath, $locpath[, $mode = 'auto']) - :param string $rempath: Remote file path - :param string $locpath: Local file path - :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') - :returns: bool + :param string $rempath: Remote file path + :param string $locpath: Local file path + :param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii') + :returns: TRUE on success, FALSE on failure + :rtype: bool Downloads a file from your server. You must supply the remote path and the local path, and you can optionally set the mode. Example:: @@ -166,14 +169,16 @@ Class Reference If 'auto' mode is used it will base the mode on the file extension of the source file. - Returns FALSE if the download does not execute successfully (including if PHP does not have permission to write the local file). + Returns FALSE if the download does not execute successfully + (including if PHP does not have permission to write the local file). - .. method:: rename($old_file, $new_file, $move = FALSE) + .. method:: rename($old_file, $new_file[, $move = FALSE]) - :param string $old_file: Old file name - :param string $new_file: New file name - :param bool $move: Whether a move is being performed - :returns: bool + :param string $old_file: Old file name + :param string $new_file: New file name + :param bool $move: Whether a move is being performed + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to rename a file. Supply the source file name/path and the new file name/path. :: @@ -183,9 +188,10 @@ Class Reference .. method:: move($old_file, $new_file) - :param string $old_file: Old file name - :param string $new_file: New file name - :returns: bool + :param string $old_file: Old file name + :param string $new_file: New file name + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you move a file. Supply the source and destination paths:: @@ -196,8 +202,9 @@ Class Reference .. method:: delete_file($filepath) - :param string $filepath: Path to file to delete - :returns: bool + :param string $filepath: Path to file to delete + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you delete a file. Supply the source path with the file name. :: @@ -206,8 +213,9 @@ Class Reference .. method:: delete_dir($filepath) - :param string $filepath: Path to directory to delete - :returns: bool + :param string $filepath: Path to directory to delete + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you delete a directory and everything it contains. Supply the source path to the directory with a trailing slash. @@ -223,8 +231,9 @@ Class Reference .. method:: list_files([$path = '.']) - :param string $path: Directory path - :returns: array or FALSE on failure + :param string $path: Directory path + :returns: An array list of files or FALSE on failure + :rtype: array Permits you to retrieve a list of files on your server returned as an array. You must supply the path to the desired directory. @@ -235,9 +244,10 @@ Class Reference .. method:: mirror($locpath, $rempath) - :param string $locpath: Local path - :param string $rempath: Remote path - :returns: bool + :param string $locpath: Local path + :param string $rempath: Remote path + :returns: TRUE on success, FALSE on failure + :rtype: bool Recursively reads a local folder and everything it contains (including sub-folders) and creates a mirror via FTP based on it. Whatever the @@ -248,9 +258,10 @@ Class Reference .. method:: mkdir($path[, $permissions = NULL]) - :param string $path: Path to directory to create - :param int $permissions: Permissions (octal) - :returns: bool + :param string $path: Path to directory to create + :param int $permissions: Permissions (octal) + :returns: TRUE on success, FALSE on failure + :rtype: bool Lets you create a directory on your server. Supply the path ending in the folder name you wish to create, with a trailing slash. @@ -263,9 +274,10 @@ Class Reference .. method:: chmod($path, $perm) - :param string $path: Path to alter permissions for - :param int $perm: Permissions (octal) - :returns: bool + :param string $path: Path to alter permissions for + :param int $perm: Permissions (octal) + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to set file permissions. Supply the path to the file or directory you wish to alter permissions on:: @@ -275,9 +287,10 @@ Class Reference .. method:: changedir($path[, $suppress_debug = FALSE]) - :param string $path: Directory path - :param bool $suppress_debug: Whether to turn off debug messages for this command - :returns: bool + :param string $path: Directory path + :param bool $suppress_debug: Whether to turn off debug messages for this command + :returns: TRUE on success, FALSE on failure + :rtype: bool Changes the current working directory to the specified path. @@ -286,7 +299,8 @@ Class Reference .. method:: close() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool Closes the connection to your server. It's recommended that you use this when you are finished uploading.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/image_lib.rst b/user_guide_src/source/libraries/image_lib.rst index cf23e397a..16acf090b 100644 --- a/user_guide_src/source/libraries/image_lib.rst +++ b/user_guide_src/source/libraries/image_lib.rst @@ -318,14 +318,16 @@ Class Reference .. method:: initialize([$props = array()]) - :param array $props: Image processing preferences - :returns: void + :param array $props: Image processing preferences + :returns: TRUE on success, FALSE in case of invalid settings + :rtype: bool Initializes the class for processing an image. .. method:: resize() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The image resizing method lets you resize the original image, create a copy (with or without resizing), or create a thumbnail image. @@ -371,14 +373,15 @@ Class Reference .. method:: crop() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The cropping method works nearly identically to the resizing function except it requires that you set preferences for the X and Y axis (in pixels) specifying where to crop, like this:: - $config['x_axis'] = '100'; - $config['y_axis'] = '40'; + $config['x_axis'] = 100; + $config['y_axis'] = 40; All preferences listed in the :ref:`processing-preferences` table are available for this method except these: *rotation_angle*, *create_thumb* and *new_image*. @@ -388,8 +391,8 @@ Class Reference $config['image_library'] = 'imagemagick'; $config['library_path'] = '/usr/X11R6/bin/'; $config['source_image'] = '/path/to/image/mypic.jpg'; - $config['x_axis'] = '100'; - $config['y_axis'] = '60'; + $config['x_axis'] = 100; + $config['y_axis'] = 60; $this->image_lib->initialize($config); @@ -406,7 +409,8 @@ Class Reference .. method:: rotate() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The image rotation method requires that the angle of rotation be set via its preference:: @@ -437,14 +441,15 @@ Class Reference .. method:: watermark() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool Creates a watermark over an image, please refer to the :ref:`watermarking` section for more info. .. method:: clear() - :returns: void + :rtype: void The clear method resets all of the values used when processing an image. You will want to call this if you are processing images in a @@ -456,9 +461,10 @@ Class Reference .. method:: display_errors([$open = '<p>[, $close = '</p>']]) - :param string $open: Error message opening tag - :param string $close: Error message closing tag - :returns: string + :param string $open: Error message opening tag + :param string $close: Error message closing tag + :returns: Error messages + :rtype: string Returns all detected errors formatted as a string. :: diff --git a/user_guide_src/source/libraries/input.rst b/user_guide_src/source/libraries/input.rst index 8a83207af..7ebf0e1c7 100644 --- a/user_guide_src/source/libraries/input.rst +++ b/user_guide_src/source/libraries/input.rst @@ -68,10 +68,10 @@ With CodeIgniter's built in methods you can simply do this:: The main methods are: -- $this->input->post() -- $this->input->get() -- $this->input->cookie() -- $this->input->server() +- ``$this->input->post()`` +- ``$this->input->get()`` +- ``$this->input->cookie()`` +- ``$this->input->server()`` Using the php://input stream ============================ @@ -108,9 +108,10 @@ Class Reference .. method:: post([$index = NULL[, $xss_clean = NULL]]) - :param string $index: POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: POST parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_POST if no parameters supplied, otherwise the POST value if found or NULL if not + :rtype: mixed The first parameter will contain the name of the POST item you are looking for:: @@ -138,9 +139,10 @@ Class Reference .. method:: get([$index = NULL[, $xss_clean = NULL]]) - :param string $index: GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: GET parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_GET if no parameters supplied, otherwise the GET value if found or NULL if not + :rtype: mixed This method is identical to ``post()``, only it fetches GET data. :: @@ -158,9 +160,10 @@ Class Reference .. method:: post_get([$index = ''[, $xss_clean = NULL]]) - :param string $index: POST/GET parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: POST/GET parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: POST/GET value if found, NULL if not + :rtype: mixed This method works the same way as ``post()`` and ``get()``, only combined. It will search through both POST and GET streams for data, looking in POST @@ -170,9 +173,10 @@ Class Reference .. method:: get_post([$index = ''[, $xss_clean = NULL]]) - :param string $index: GET/POST parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: GET/POST parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: GET/POST value if found, NULL if not + :rtype: mixed This method works the same way as ``post_get()`` only it looks for GET data first. @@ -184,9 +188,10 @@ Class Reference .. method:: cookie([$index = ''[, $xss_clean = NULL]]) - :param string $index: COOKIE parameter name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: COOKIE parameter name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_COOKIE if no parameters supplied, otherwise the COOKIE value if found or NULL if not + :rtype: mixed This method is identical to ``post()`` and ``get()``, only it fetches cookie data:: @@ -196,9 +201,10 @@ Class Reference .. method:: server([$index = ''[, $xss_clean = NULL]]) - :param string $index: Value name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: Value name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: $_SERVER item value if found, NULL if not + :rtype: mixed This method is identical to the ``post()``, ``get()`` and ``cookie()`` methods, only it fetches server data (``$_SERVER``):: @@ -207,24 +213,26 @@ Class Reference .. method:: input_stream([$index = ''[, $xss_clean = NULL]]) - :param string $index: Key name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: mixed + :param string $index: Key name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: Input stream array if no parameters supplied, otherwise the specified value if found or NULL if not + :rtype: mixed This method is identical to ``get()``, ``post()`` and ``cookie()``, only it fetches the *php://input* stream data. .. method:: set_cookie($name = ''[, $value = ''[, $expire = ''[, $domain = ''[, $path = '/'[, $prefix = ''[, $secure = FALSE[, $httponly = FALSE]]]]]]]) - :param mixed $name: Cookie name or an array of parameters - :param string $value: Cookie value - :param int $expire: Cookie expiration time in seconds - :param string $domain: Cookie domain - :param string $path: Cookie path - :param string $prefix: Cookie name prefix - :param bool $secure: Whether to only transfer the cookie through HTTPS - :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) - :returns: void + :param mixed $name: Cookie name or an array of parameters + :param string $value: Cookie value + :param int $expire: Cookie expiration time in seconds + :param string $domain: Cookie domain + :param string $path: Cookie path + :param string $prefix: Cookie name prefix + :param bool $secure: Whether to only transfer the cookie through HTTPS + :param bool $httponly: Whether to only make the cookie accessible for HTTP requests (no JavaScript) + :rtype: void + Sets a cookie containing the values you specify. There are two ways to pass information to this method so that a cookie can be set: Array @@ -247,7 +255,7 @@ Class Reference $this->input->set_cookie($cookie); - **Notes:** + **Notes** Only the name and value are required. To delete a cookie set it with the expiration blank. @@ -276,10 +284,10 @@ Class Reference $this->input->set_cookie($name, $value, $expire, $domain, $path, $prefix, $secure); - .. method:: ip_address() - :returns: string + :returns: Visitor's IP address or '0.0.0.0' if not valid + :rtype: string Returns the IP address for the current user. If the IP address is not valid, the method will return '0.0.0.0':: @@ -293,9 +301,10 @@ Class Reference .. method:: valid_ip($ip[, $which = '']) - :param string $ip: IP address - :param string $which: IP protocol ('ipv4' or 'ipv6') - :returns: bool + :param string $ip: IP address + :param string $which: IP protocol ('ipv4' or 'ipv6') + :returns: TRUE if the address is valid, FALSE if not + :rtype: bool Takes an IP address as input and returns TRUE or FALSE (boolean) depending on whether it is valid or not. @@ -319,7 +328,8 @@ Class Reference .. method:: user_agent() - :returns: string + :returns: User agent string or NULL if not set + :rtype: mixed Returns the user agent string (web browser) being used by the current user, or NULL if it's not available. @@ -332,8 +342,9 @@ Class Reference .. method:: request_headers([$xss_clean = FALSE]) - :param bool $xss_clean: Whether to apply XSS filtering - :returns: array + :param bool $xss_clean: Whether to apply XSS filtering + :returns: An array of HTTP request headers + :rtype: array Returns an array of HTTP request headers. Useful if running in a non-Apache environment where @@ -345,9 +356,10 @@ Class Reference .. method:: get_request_header($index[, $xss_clean = FALSE]) - :param string $index: HTTP request header name - :param bool $xss_clean: Whether to apply XSS filtering - :returns: string + :param string $index: HTTP request header name + :param bool $xss_clean: Whether to apply XSS filtering + :returns: An HTTP request header or NULL if not found + :rtype: string Returns a single member of the request headers array or NULL if the searched header is not found. @@ -357,14 +369,16 @@ Class Reference .. method:: is_ajax_request() - :returns: bool + :returns: TRUE if it is an Ajax request, FALSE if not + :rtype: bool Checks to see if the HTTP_X_REQUESTED_WITH server header has been set, and returns boolean TRUE if it is or FALSE if not. .. method:: is_cli_request() - :returns: bool + :returns: TRUE if it is a CLI request, FALSE if not + :rtype: bool Checks to see if the application was run from the command-line interface. @@ -382,8 +396,9 @@ Class Reference .. method:: method([$upper = FALSE]) - :param bool $upper: Whether to return the request method name in upper or lower case - :returns: string + :param bool $upper: Whether to return the request method name in upper or lower case + :returns: HTTP request method + :rtype: string Returns the ``$_SERVER['REQUEST_METHOD']``, with the option to set it in uppercase or lowercase. diff --git a/user_guide_src/source/libraries/language.rst b/user_guide_src/source/libraries/language.rst index 10449b935..3014d8f09 100644 --- a/user_guide_src/source/libraries/language.rst +++ b/user_guide_src/source/libraries/language.rst @@ -110,20 +110,22 @@ Class Reference .. method:: load($langfile[, $idiom = ''[, $return = FALSE[, $add_suffix = TRUE[, $alt_path = '']]]]) - :param string $langfile: Language file to load - :param string $idiom: Language name (i.e. 'english') - :param bool $return: Whether to return the loaded array of translations - :param bool $add_suffix: Whether to add the '_lang' suffix to the language file name - :param string $alt_path: An alternative path to look in for the language file - :returns: void or array if the third parameter is set to TRUE + :param string $langfile: Language file to load + :param string $idiom: Language name (i.e. 'english') + :param bool $return: Whether to return the loaded array of translations + :param bool $add_suffix: Whether to add the '_lang' suffix to the language file name + :param string $alt_path: An alternative path to look in for the language file + :returns: Array of language lines if $return is set to TRUE, otherwise void + :rtype: mixed Loads a language file. .. method:: line($line[, $log_errors = TRUE]) - :param string $line: Language line key name - :param bool $log_errors: Whether to log an error if the line isn't found - :returns: string or FALSE on failure + :param string $line: Language line key name + :param bool $log_errors: Whether to log an error if the line isn't found + :returns: Language line string or FALSE on failure + :rtype: string Fetches a single translation line from the already loaded language files, based on the line's name.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst index 15d9d80fc..107b3ece3 100644 --- a/user_guide_src/source/libraries/loader.rst +++ b/user_guide_src/source/libraries/loader.rst @@ -80,10 +80,11 @@ Class Reference .. method:: library($library[, $params = NULL[, $object_name = NULL]]) - :param mixed $library: Library name as a string or an array with multiple libraries - :param array $params: Optional array of parameters to pass to the loaded library's constructor - :param string $object_name: Optional object name to assign the library to - :returns: object + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method is used to load core classes. @@ -156,10 +157,11 @@ Class Reference .. method:: driver($library[, $params = NULL[, $object_name]]) - :param mixed $library: Library name as a string or an array with multiple libraries - :param array $params: Optional array of parameters to pass to the loaded library's constructor - :param string $object_name: Optional object name to assign the library to - :returns: object + :param mixed $library: Library name as a string or an array with multiple libraries + :param array $params: Optional array of parameters to pass to the loaded library's constructor + :param string $object_name: Optional object name to assign the library to + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method is used to load driver libraries, acts very much like the ``library()`` method. @@ -216,10 +218,11 @@ Class Reference .. method:: view($view[, $vars = array()[, return = FALSE]]) - :param string $view: View name - :param array $vars: An associative array of variables - :param bool $return: Whether to return the loaded view - :returns: mixed + :param string $view: View name + :param array $vars: An associative array of variables + :param bool $return: Whether to return the loaded view + :returns: View content string if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed This method is used to load your View files. If you haven't read the :doc:`Views <../general/views>` section of the user guide it is @@ -249,9 +252,10 @@ Class Reference .. method:: vars($vars[, $val = '']) - :param mixed $vars: An array of variables or a single variable name - :param mixed $val: Optional variable value - :returns: object + :param mixed $vars: An array of variables or a single variable name + :param mixed $val: Optional variable value + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method takes an associative array as input and generates variables using the PHP `extract() <http://www.php.net/extract>`_ @@ -265,8 +269,9 @@ Class Reference .. method:: get_var($key) - :param string $key: Variable name key - :returns: mixed + :param string $key: Variable name key + :returns: Value if key is found, NULL if not + :rtype: mixed This method checks the associative array of variables available to your views. This is useful if for any reason a var is set in a library @@ -274,22 +279,25 @@ Class Reference .. method:: get_vars() - :returns: array + :returns: An array of all assigned view variables + :rtype: array This method retrieves all variables available to your views. .. method:: clear_vars() - :returns: object + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader Clears cached view variables. .. method:: model($model[, $name = ''[, $db_conn = FALSE]]) - :param mixed $model: Model name or an array containing multiple models - :param string $name: Optional object name to assign the model to - :param string $db_conn: Optional database configuration group to load - :returns: object + :param mixed $model: Model name or an array containing multiple models + :param string $name: Optional object name to assign the model to + :param string $db_conn: Optional database configuration group to load + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader :: @@ -310,10 +318,11 @@ Class Reference .. method:: database([$params = ''[, $return = FALSE[, $query_builder = NULL]]]) - :param mixed $params: Database group name or configuration options - :param bool $return: Whether to return the loaded database object - :param bool $query_builder: Whether to load the Query Builder - :returns: mixed + :param mixed $params: Database group name or configuration options + :param bool $return: Whether to return the loaded database object + :param bool $query_builder: Whether to load the Query Builder + :returns: Loaded CI_DB instance or FALSE on failure if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed This method lets you load the database class. The two parameters are **optional**. Please see the :doc:`database <../database/index>` @@ -321,35 +330,39 @@ Class Reference .. method:: dbforge([$db = NULL[, $return = FALSE]]) - :param object $db: Database object - :param bool $return: Whether to return the Database Forge instance - :returns: mixed + :param object $db: Database object + :param bool $return: Whether to return the Database Forge instance + :returns: Loaded CI_DB_forge instance if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed Loads the :doc:`Database Forge <../database/forge>` class, please refer to that manual for more info. .. method:: dbutil([$db = NULL[, $return = FALSE]]) - :param object $db: Database object - :param bool $return: Whether to return the Database Utilities instance - :returns: mixed + :param object $db: Database object + :param bool $return: Whether to return the Database Utilities instance + :returns: Loaded CI_DB_utility instance if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed Loads the :doc:`Database Utilities <../database/utilities>` class, please refer to that manual for more info. .. method:: helper($helpers) - :param mixed $helpers: Helper name as a string or an array containing multiple helpers - :returns: object + :param mixed $helpers: Helper name as a string or an array containing multiple helpers + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method loads helper files, where file_name is the name of the file, without the _helper.php extension. .. method:: file($path[, $return = FALSE]) - :param string $path: File path - :param bool $return: Whether to return the loaded file - :returns: mixed + :param string $path: File path + :param bool $return: Whether to return the loaded file + :returns: File contents if $return is set to TRUE, otherwise CI_Loader instance (method chaining) + :rtype: mixed This is a generic file loading method. Supply the filepath and name in the first parameter and it will open and read the file. By default the @@ -359,27 +372,30 @@ Class Reference .. method:: language($files[, $lang = '']) - :param mixed $files: Language file name or an array of multiple language files - :param string $lang: Language name - :returns: object + :param mixed $files: Language file name or an array of multiple language files + :param string $lang: Language name + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader This method is an alias of the :doc:`language loading method <language>`: ``$this->lang->load()``. .. method:: config($file[, $use_sections = FALSE[, $fail_gracefully = FALSE]]) - :param string $file: Configuration file name - :param bool $use_sections: Whether configuration values should be loaded into their own section - :param bool $fail_gracefully: Whether to just return FALSE in case of failure - :returns: bool + :param string $file: Configuration file name + :param bool $use_sections: Whether configuration values should be loaded into their own section + :param bool $fail_gracefully: Whether to just return FALSE in case of failure + :returns: TRUE on success, FALSE on failure + :rtype: bool This method is an alias of the :doc:`config file loading method <config>`: ``$this->config->load()`` .. method:: is_loaded($class) - :param string $class: Class name - :returns: mixed + :param string $class: Class name + :returns: Singleton property name if found, FALSE if not + :rtype: mixed Allows you to check if a class has already been loaded or not. @@ -405,9 +421,10 @@ Class Reference .. method:: add_package_path($path[, $view_cascade = TRUE]) - :param string $path: Path to add - :param bool $view_cascade: Whether to use cascading views - :returns: object + :param string $path: Path to add + :param bool $view_cascade: Whether to use cascading views + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader Adding a package path instructs the Loader class to prepend a given path for subsequent requests for resources. As an example, the "Foo Bar" @@ -419,8 +436,9 @@ Class Reference .. method:: remove_package_path([$path = '']) - :param string $path: Path to remove - :returns: object + :param string $path: Path to remove + :returns: CI_Loader instance (method chaining) + :rtype: CI_Loader When your controller is finished using resources from an application package, and particularly if you have other application packages you @@ -435,7 +453,8 @@ Class Reference .. method:: get_package_paths([$include_base = TRUE]) - :param bool $include_base: Whether to include BASEPATH - :returns: array + :param bool $include_base: Whether to include BASEPATH + :returns: An array of package paths + :rtype: array Returns all currently available package paths.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst index 4143609bb..e8ea1d977 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -142,25 +142,30 @@ Class Reference .. method:: current() - :returns: mixed + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed - Migrates up to the current version (whatever is set for ``$config['migration_version']`` in *application/config/migration.php*). + Migrates up to the current version (whatever is set for + ``$config['migration_version']`` in *application/config/migration.php*). .. method:: error_string() - :returns: string + :returns: Error messages + :rtype: string This returns a string of errors that were detected while performing a migration. .. method:: find_migrations() - :returns: array + :returns: An array of migration files + :rtype: array An array of migration filenames are returned that are found in the **migration_path** property. .. method:: latest() - :returns: mixed + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed This works much the same way as ``current()`` but instead of looking for the ``$config['migration_version']`` the Migration class will use the very @@ -168,11 +173,12 @@ Class Reference .. method:: version($target_version) - :param mixed $target_version: Migration version to process - :returns: mixed + :param mixed $target_version: Migration version to process + :returns: TRUE if no migrations are found, current version string on success, FALSE on failure + :rtype: mixed Version can be used to roll back changes or step forwards programmatically to specific versions. It works just like ``current()`` but ignores ``$config['migration_version']``. :: - $this->migration->version(5); + $this->migration->version(5);
\ No newline at end of file diff --git a/user_guide_src/source/libraries/output.rst b/user_guide_src/source/libraries/output.rst index 76197bdc1..e49ea5366 100644 --- a/user_guide_src/source/libraries/output.rst +++ b/user_guide_src/source/libraries/output.rst @@ -43,8 +43,9 @@ Class Reference .. method:: set_output($output) - :param string $output: String to set the output to - :returns: object + :param string $output: String to set the output to + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set the final output string. Usage example:: @@ -52,13 +53,14 @@ Class Reference .. important:: If you do set your output manually, it must be the last thing done in the function you call it from. For example, if you build a page in one - of your controller functions, don't set the output until the end. + of your controller methods, don't set the output until the end. .. method:: set_content_type($mime_type[, $charset = NULL]) - :param string $mime_type: MIME Type idenitifer string - :param string $charset: Character set - :returns: object + :param string $mime_type: MIME Type idenitifer string + :param string $charset: Character set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to set the mime-type of your page so you can serve JSON data, JPEG's, XML, etc easily. :: @@ -80,7 +82,8 @@ Class Reference .. method:: get_content_type() - :returns: string + :returns: Content-Type string + :rtype: string Returns the Content-Type HTTP header that's currently in use, excluding the character set value. :: @@ -91,8 +94,9 @@ Class Reference .. method:: get_header($header) - :param string $header: HTTP header name - :returns: string + :param string $header: HTTP header name + :returns: HTTP response header or NULL if not found + :rtype: mixed Returns the requested HTTP header value, or NULL if the requested header is not set. Example:: @@ -107,7 +111,8 @@ Class Reference .. method:: get_output() - :returns: string + :returns: Output string + :rtype: string Permits you to manually retrieve any output that has been sent for storage in the output class. Usage example:: @@ -120,8 +125,9 @@ Class Reference .. method:: append_output($output) - :param string $output: Additional output data to append - :returns: object + :param string $output: Additional output data to append + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Appends data onto the output string. :: @@ -130,9 +136,10 @@ Class Reference .. method:: set_header($header[, $replace = TRUE]) - :param string $header: HTTP Header - :param bool $replace: Whether to replace the old header value, if it is already set - :returns: object + :param string $header: HTTP response header + :param bool $replace: Whether to replace the old header value, if it is already set + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set server headers, which the output class will send for you when outputting the final rendered display. Example:: @@ -146,9 +153,10 @@ Class Reference .. method:: set_status_header([$code = 200[, $text = '']]) - :param int $code: HTTP status code - :param string $text: Optional message - :returns: object + :param int $code: HTTP status code + :param string $text: Optional message + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to manually set a server status header. Example:: @@ -162,8 +170,9 @@ Class Reference .. method:: enable_profiler([$val = TRUE]) - :param bool $val: Whether to enable or disable the Profiler - :returns: object + :param bool $val: Whether to enable or disable the Profiler + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to enable/disable the :doc:`Profiler <../general/profiling>`, which will display benchmark and other data at the bottom of your pages for debugging and optimization purposes. @@ -181,16 +190,18 @@ Class Reference .. method:: set_profiler_sections($sections) - :param array $sections: Profiler sections - :returns: object + :param array $sections: Profiler sections + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Permits you to enable/disable specific sections of the Profiler when it is enabled. Please refer to the :doc:`Profiler <../general/profiling>` documentation for further information. .. method:: cache($time) - :param int $time: Cache expiration time in seconds - :returns: object + :param int $time: Cache expiration time in seconds + :returns: CI_Output instance (method chaining) + :rtype: CI_Output Caches the current page for the specified amount of seconds. diff --git a/user_guide_src/source/libraries/pagination.rst b/user_guide_src/source/libraries/pagination.rst index 34ca22141..222436f46 100644 --- a/user_guide_src/source/libraries/pagination.rst +++ b/user_guide_src/source/libraries/pagination.rst @@ -307,13 +307,14 @@ Class Reference .. method:: initialize([$params = array()]) - :param array $params: Configuration parameters - :returns: void + :param array $params: Configuration parameters + :rtype: void Initializes the Pagination class with your preferred options. .. method:: create_links() - :returns: string + :returns: HTML-formatted pagination + :rtype: string Returns a "pagination" bar, containing the generated links or an empty string if there's just a single page.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/parser.rst b/user_guide_src/source/libraries/parser.rst index 34ad65f2b..5af504a03 100644 --- a/user_guide_src/source/libraries/parser.rst +++ b/user_guide_src/source/libraries/parser.rst @@ -151,27 +151,29 @@ Class Reference .. method:: parse($template, $data[, $return = FALSE]) - :param string $template: Path to view file - :param array $data: Variable data - :param bool $return: Whether to return the parsed template - :returns: mixed + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to only return the parsed template + :returns: Parsed template string + :rtype: string Parses a template from the provided path and variables. .. method:: parse_string($template, $data[, $return = FALSE]) - :param string $template: Path to view file - :param array $data: Variable data - :param bool $return: Whether to return the parsed template - :returns: mixed + :param string $template: Path to view file + :param array $data: Variable data + :param bool $return: Whether to only return the parsed template + :returns: Parsed template string + :rtype: string This method works exactly like ``parse()``, only it accepts the template as a string instead of loading a view file. .. method:: set_delimiters([$l = '{'[, $r = '}']]) - :param string $l: Left delimiter - :param string $r: Right delimiter - :returns: void + :param string $l: Left delimiter + :param string $r: Right delimiter + :rtype: void Sets the delimiters (opening and closing) for a value "tag" in a template.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/security.rst b/user_guide_src/source/libraries/security.rst index 451fadf93..fb875a0d9 100644 --- a/user_guide_src/source/libraries/security.rst +++ b/user_guide_src/source/libraries/security.rst @@ -105,17 +105,19 @@ Class Reference .. method:: xss_clean($str[, $is_image = FALSE]) - :param string $str: Input string - :returns: mixed + :param mixed $str: Input string or an array of strings + :returns: XSS-clean data + :rtype: 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 + :param string $str: File name/path + :param bool $relative_path: Whether to preserve any directories in the file path + :returns: Sanitized file name/path + :rtype: 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. @@ -131,23 +133,27 @@ Class Reference .. method:: get_csrf_token_name() - :returns: string + :returns: CSRF token name + :rtype: string Returns the CSRF token name (the ``$config['csrf_token_name']`` value). .. method:: get_csrf_hash() - :returns: string + :returns: CSRF hash + :rtype: 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]) - :param string $str: Input string - :param string $charset: Character set of the input string + :param string $str: Input string + :param string $charset: Character set of the input string + :returns: Entity-decoded string + :rtype: string 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. - If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used. + If the ``$charset`` parameter is left empty, then your configured ``$config['charset']`` value will be used.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/sessions.rst b/user_guide_src/source/libraries/sessions.rst index 9e23e9b60..f05f86af1 100644 --- a/user_guide_src/source/libraries/sessions.rst +++ b/user_guide_src/source/libraries/sessions.rst @@ -526,20 +526,23 @@ Class Reference .. method:: load_driver($driver) - :param string $driver: Driver name - :returns: object + :param string $driver: Driver name + :returns: Instance of currently loaded session driver + :rtype: mixed Loads a session storage driver .. method:: select_driver($driver) - :param string $driver: Driver name - :returns: void + :param string $driver: Driver name + :rtype: void Selects default session storage driver. .. method:: sess_destroy() + :rtype: void + Destroys current session .. note:: This method should be the last one called, and even flash @@ -549,15 +552,16 @@ Class Reference .. method:: sess_regenerate([$destroy = FALSE]) - :param bool $destroy: Whether to destroy session data - :returns: void + :param bool $destroy: Whether to destroy session data + :rtype: void Regenerate the current session data. .. method:: userdata([$item = NULL]) - :param string $item: Session item name - :returns: mixed + :param string $item: Session item name + :returns: Item value if found, NULL if not or an array of all userdata if $item parameter is not used + :rtype: mixed If no parameter is passed, it will return an associative array of all existing userdata. @@ -569,7 +573,8 @@ Class Reference .. method:: all_userdata() - :returns: array + :returns: An array of all userdata + :rtype: array Returns an array with all of the session userdata items. @@ -577,15 +582,16 @@ Class Reference .. method:: &get_userdata() - :returns: array + :returns: A reference to the userdata array + :rtype: &array Returns a reference to the userdata array. .. method:: set_userdata($newdata[, $newval = '']) - :param mixed $newdata: Item name or array of items - :param mixed $newval: Item value or empty string (not required if $newdata is array) - :returns: void + :param mixed $newdata: Item name or array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :rtype: void Sets items into session example usages:: @@ -597,8 +603,8 @@ Class Reference .. method:: unset_userdata($item) - :param mixed $item: Item name or an array containing multiple items - :returns: void + :param mixed $item: Item name or an array containing multiple items + :rtype: void Unsets previously set items from the session. Example:: @@ -610,15 +616,17 @@ Class Reference .. method:: has_userdata($item) - :param string $item: Item name - :returns: bool + :param string $item: Item name + :returns: TRUE if item exists, FALSE if not + :rtype: bool Checks if an item exists in the session. .. method:: flashdata([$item = NULL]) - :param string $item: Flashdata item name - :returns: mixed + :param string $item: Flashdata item name + :returns: Item value if found, NULL if not or an array of all flashdata if $item parameter is not used + :rtype: mixed If no parameter is passed, it will return an associative array of all existing flashdata. @@ -630,9 +638,9 @@ Class Reference .. method:: set_flashdata($newdata[, $newval = '']) - :param mixed $newdata: Item name or an array of items - :param mixed $newval: Item value or empty string (not required if $newdata is array) - :returns: void + :param mixed $newdata: Item name or an array of items + :param mixed $newval: Item value or empty string (not required if $newdata is array) + :rtype: void Sets items into session flashdata example usages:: @@ -645,15 +653,16 @@ Class Reference .. method:: keep_flashdata($item) - :param mixed $item: Item name or an array containing multiple flashdata items - :returns: void + :param mixed $item: Item name or an array containing multiple flashdata items + :rtype: void Keeps items into flashdata for one more request. .. method:: tempdata([$item = NULL]) - :param string $item: Tempdata item name - :returns: mixed + :param string $item: Tempdata item name + :returns: Item value if found, NULL if not or an array of all tempdata if $item parameter is not used + :rtype: mixed If no parameter is passed, it will return an associative array of all existing tempdata. @@ -665,10 +674,10 @@ Class Reference .. method:: set_tempdata($newdata[, $newval = ''[, $expire = 0]]) - :param mixed $newdata: Item name or array containing multiple items - :param string $newval: Item value or empty string (not required if $newdata is array) - :param int $expire: Lifetime in seconds (0 for default) - :returns: void + :param mixed $newdata: Item name or array containing multiple items + :param string $newval: Item value or empty string (not required if $newdata is array) + :param int $expire: Lifetime in seconds (0 for default) + :rtype: void Sets items into session tempdata example:: @@ -681,8 +690,8 @@ Class Reference .. method:: unset_tempdata($item) - :param mixed $item: Item name or an array containing multiple items - :returns: void + :param mixed $item: Item name or an array containing multiple items + :rtype: void Unsets previously set items from tempdata. Example:: diff --git a/user_guide_src/source/libraries/table.rst b/user_guide_src/source/libraries/table.rst index ed085f781..ea0c417c4 100644 --- a/user_guide_src/source/libraries/table.rst +++ b/user_guide_src/source/libraries/table.rst @@ -158,15 +158,16 @@ Class Reference .. method:: generate([$table_data = NULL]) - :param mixed $table_data: data to populate the table rows with - :returns: string + :param mixed $table_data: Data to populate the table rows with + :returns: HTML table + :rtype: string Returns a string containing the generated table. Accepts an optional parameter which can be an array or a database result object. .. method:: set_caption($caption) - :param string $caption: table caption - :returns: void + :param string $caption: Table caption + :rtype: void Permits you to add a caption to the table. :: @@ -175,8 +176,8 @@ Class Reference .. method:: set_heading([$args = array()[, ...]]) - :param mixed $args: an array or multiple strings containing the table column titles - :returns: void + :param mixed $args: An array or multiple strings containing the table column titles + :rtype: void Permits you to set the table heading. You can submit an array or discrete params:: @@ -186,8 +187,8 @@ Class Reference .. method:: add_row([$args = array()[, ...]]) - :param mixed $args: an array or multiple strings containing the row values - :returns: void + :param mixed $args: An array or multiple strings containing the row values + :rtype: void Permits you to add a row to your table. You can submit an array or discrete params:: @@ -206,9 +207,10 @@ Class Reference .. method:: make_columns([$array = array()[, $col_limit = 0]]) - :param array $array: an array containing multiple rows' data - :param int $col_limit: count of columns in the table - :returns: array + :param array $array: An array containing multiple rows' data + :param int $col_limit: Count of columns in the table + :returns: An array of HTML table columns + :rtype: array 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:: @@ -235,8 +237,9 @@ Class Reference .. method:: set_template($template) - :param array $template: associative array containing template values - :returns: bool + :param array $template: An associative array containing template values + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to set your template. You can submit a full or partial template. :: @@ -249,8 +252,8 @@ Class Reference .. method:: set_empty($value) - :param mixed $value: value to put in empty cells - :returns: void + :param mixed $value: Value to put in empty cells + :rtype: 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:: @@ -259,7 +262,7 @@ Class Reference .. method:: clear() - :returns: void + :rtype: 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:: diff --git a/user_guide_src/source/libraries/trackback.rst b/user_guide_src/source/libraries/trackback.rst index c5b01a2ee..22859a13d 100644 --- a/user_guide_src/source/libraries/trackback.rst +++ b/user_guide_src/source/libraries/trackback.rst @@ -225,22 +225,24 @@ Class Reference .. method:: send($tb_data) - :param array $tb_data: trackback data - :returns: bool + :param array $tb_data: Trackback data + :returns: TRUE on success, FALSE on failure + :rtype: bool Send trackback. .. method:: receive() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool This method simply validates the incoming TB data, returning TRUE on success and FALSE on failure. If the data is valid it is set to the ``$this->data`` array so that it can be inserted into a database. .. method:: send_error([$message = 'Incomplete information') - :param string $message: error message - :returns: void + :param string $message: Error message + :rtype: void Responses to a trackback request with an error message. @@ -248,7 +250,7 @@ Class Reference .. method:: send_success() - :returns: void + :rtype: void Responses to a trackback request with a success message. @@ -256,74 +258,82 @@ Class Reference .. method:: data($item) - :param string $item: data key - :returns: string + :param string $item: Data key + :returns: Data value or empty string if not found + :rtype: string Returns a single item from the reponse data array. .. method:: process($url, $data) - :param string $url: target url - :param string $data: raw post data - :returns: bool + :param string $url: Target url + :param string $data: Raw POST data + :returns: TRUE on success, FALSE on failure + :rtype: bool Opens a socket connection and passes the data to the server, returning TRUE on success and FALSE on failure. .. method:: extract_urls($urls) - :param string $urls: comma-separated url list - :returns: string + :param string $urls: Comma-separated URL list + :returns: Array of URLs + :rtype: array This method lets multiple trackbacks to be sent. It takes a string of URLs (separated by comma or space) and puts each URL into an array. .. method:: validate_url(&$url) - :param string $url: trackback url - :returns: void + :param string $url: Trackback URL + :rtype: void Simply adds the *http://* prefix it it's not already present in the URL. .. method:: get_id($url) - :param string $url: trackback url - :returns: string + :param string $url: Trackback URL + :returns: URL ID or FALSE on failure + :rtype: string Find and return a trackback URL's ID or FALSE on failure. .. method:: convert_xml($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Converted string + :rtype: string Converts reserved XML characters to entities. .. method:: limit_characters($str[, $n = 500[, $end_char = '…']]) - :param string $str: input string - :param int $n: max characters number - :param string $end_char: character to put at end of string - :returns: string + :param string $str: Input string + :param int $n: Max characters number + :param string $end_char: Character to put at end of string + :returns: Shortened string + :rtype: string Limits the string based on the character count. Will preserve complete words. .. method:: convert_ascii($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Converted string + :rtype: string Converts high ASCII text and MS Word special characterss to HTML entities. .. method:: set_error($msg) - :param string $msg: error message - :returns: void + :param string $msg: Error message + :rtype: void Set an log an error message. .. method:: display_errors([$open = '<p>'[, $close = '</p>']]) - :param string $open: open tag - :param string $close: close tag - :returns: string + :param string $open: Open tag + :param string $close: Close tag + :returns: HTML formatted error messages + :rtype: string Returns error messages formatted in HTML or an empty string if there are no errors.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/typography.rst b/user_guide_src/source/libraries/typography.rst index c1a864a3e..65fea9d8e 100644 --- a/user_guide_src/source/libraries/typography.rst +++ b/user_guide_src/source/libraries/typography.rst @@ -46,9 +46,10 @@ Class Reference .. method auto_typography($str[, $reduce_linebreaks = FALSE]) - :param string $str: input string - :param bool $reduce_linebreaks: whether to reduce consequitive linebreaks - :returns: string + :param string $str: Input string + :param bool $reduce_linebreaks: Whether to reduce consequitive linebreaks + :returns: HTML typography-safe string + :rtype: string Formats text so that it is semantically and typographically correct HTML. Takes a string as input and returns it with the following formatting: @@ -76,8 +77,9 @@ Class Reference .. method:: format_characters($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Formatted string + :rtype: string This method is similar to ``auto_typography()`` above, except that it only does character conversion: @@ -93,8 +95,9 @@ Class Reference .. method:: nl2br_except_pre($str) - :param string $str: input string - :returns: string + :param string $str: Input string + :returns: Formatted string + :rtype: string Converts newlines to <br /> tags unless they appear within <pre> tags. This method is identical to the native PHP :php:func:`nl2br()` function, except that it ignores <pre> tags. diff --git a/user_guide_src/source/libraries/unit_testing.rst b/user_guide_src/source/libraries/unit_testing.rst index 2d4a27a25..0bc860f61 100644 --- a/user_guide_src/source/libraries/unit_testing.rst +++ b/user_guide_src/source/libraries/unit_testing.rst @@ -193,45 +193,48 @@ Class Reference .. method:: run($test[, $expected = TRUE[, $test_name = 'undefined'[, $notes = '']]]) - :param mixed $test: Test data - :param mixed $expected: Expected result - :param string $test_name: Test name - :param string $notes: Any notes to be attached to the test - :returns: string + :param mixed $test: Test data + :param mixed $expected: Expected result + :param string $test_name: Test name + :param string $notes: Any notes to be attached to the test + :returns: Test report + :rtype: string Runs unit tests. .. method:: report([$result = array()]) - :param array $result: Array containing tests results - :returns: string + :param array $result: Array containing tests results + :returns: Test report + :rtype: string Generates a report about already complete tests. .. method:: use_strict([$state = TRUE]) - :param bool $state: Strict state flag - :returns: void + :param bool $state: Strict state flag + :rtype: void Enables/disables strict type comparison in tests. .. method:: active([$state = TRUE]) - :param bool $state: Whether to enable testing - :returns: void + :param bool $state: Whether to enable testing + :rtype: void Enables/disables unit testing. .. method:: result([$results = array()]) - :param array $results: Tests results list - :returns: array + :param array $results: Tests results list + :returns: Array of raw result data + :rtype: array Returns raw tests results data. .. method:: set_template($template) - :param string $template: Test result template - :returns: void + :param string $template: Test result template + :rtype: void Sets the template for displaying tests results.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/uri.rst b/user_guide_src/source/libraries/uri.rst index f0fa04005..7db758ce7 100644 --- a/user_guide_src/source/libraries/uri.rst +++ b/user_guide_src/source/libraries/uri.rst @@ -24,9 +24,10 @@ Class Reference .. method:: segment($n[, $no_result = NULL]) - :param int $n: Segment index number - :param mixed $no_result: What to return if the searched segment is not found - :returns: mixed + :param int $n: Segment index number + :param mixed $no_result: What to return if the searched segment is not found + :returns: Segment value or $no_result value if not found + :rtype: mixed Permits you to retrieve a specific segment. Where n is the segment number you wish to retrieve. Segments are numbered from left to right. @@ -60,9 +61,10 @@ Class Reference .. method:: rsegment($n[, $no_result = NULL]) - :param int $n: Segment index number - :param mixed $no_result: What to return if the searched segment is not found - :returns: mixed + :param int $n: Segment index number + :param mixed $no_result: What to return if the searched segment is not found + :returns: Routed segment value or $no_result value if not found + :rtype: mixed This method is identical to ``segment()``, except that it lets you retrieve a specific segment from your re-routed URI in the event you are @@ -70,9 +72,10 @@ Class Reference .. method:: slash_segment($n[, $where = 'trailing']) - :param int $n: Segment index number - :param string $where: Where to add the slash ('trailing' or 'leading') - :returns: string + :param int $n: Segment index number + :param string $where: Where to add the slash ('trailing' or 'leading') + :returns: Segment value, prepended/suffixed with a forward slash, or a slash if not found + :rtype: string This method is almost identical to ``segment()``, except it adds a trailing and/or leading slash based on the second parameter. @@ -90,9 +93,10 @@ Class Reference .. method:: slash_rsegment($n[, $where = 'trailing']) - :param int $n: Segment index number - :param string $where: Where to add the slash ('trailing' or 'leading') - :returns: string + :param int $n: Segment index number + :param string $where: Where to add the slash ('trailing' or 'leading') + :returns: Routed segment value, prepended/suffixed with a forward slash, or a slash if not found + :rtype: string This method is identical to ``slash_segment()``, except that it lets you add slashes a specific segment from your re-routed URI in the event you @@ -101,9 +105,10 @@ Class Reference .. method:: uri_to_assoc([$n = 3[, $default = array()]]) - :param int $n: Segment index number - :param array $default: Default values - :returns: array + :param int $n: Segment index number + :param array $default: Default values + :returns: Associative URI segments array + :rtype: array This method lets you turn URI segments into and associative array of key/value pairs. Consider this URI:: @@ -142,9 +147,10 @@ Class Reference .. method:: ruri_to_assoc([$n = 3[, $default = array()]]) - :param int $n: Segment index number - :param array $default: Default values - :returns: array + :param int $n: Segment index number + :param array $default: Default values + :returns: Associative routed URI segments array + :rtype: array This method is identical to ``uri_to_assoc()``, except that it creates an associative array using the re-routed URI in the event you are using @@ -152,8 +158,9 @@ Class Reference .. method:: assoc_to_uri($array) - :param array $array: Input array of key/value pairs - :returns: string + :param array $array: Input array of key/value pairs + :returns: URI string + :rtype: string Takes an associative array as input and generates a URI string from it. The array keys will be included in the string. Example:: @@ -165,7 +172,8 @@ Class Reference .. method:: uri_string() - :returns: string + :returns: URI string + :rtype: string Returns a string with the complete URI. For example, if this is your full URL:: @@ -177,7 +185,8 @@ Class Reference .. method:: ruri_string() - :returns: string + :returns: Routed URI string + :rtype: string This method is identical to ``uri_string()``, except that it returns the re-routed URI in the event you are using CodeIgniter's :doc:`URI @@ -185,13 +194,15 @@ Class Reference .. method:: total_segments() - :returns: int + :returns: Count of URI segments + :rtype: int Returns the total number of segments. .. method:: total_rsegments() - :returns: int + :returns: Count of routed URI segments + :rtype: int This method is identical to ``total_segments()``, except that it returns the total number of segments in your re-routed URI in the event you are @@ -199,7 +210,8 @@ Class Reference .. method:: segment_array() - :returns: array + :returns: URI segments array + :rtype: array Returns an array containing the URI segments. For example:: @@ -213,7 +225,8 @@ Class Reference .. method:: rsegment_array() - :returns: array + :returns: Routed URI segments array + :rtype: array This method is identical to ``segment_array()``, except that it returns the array of segments in your re-routed URI in the event you are using diff --git a/user_guide_src/source/libraries/user_agent.rst b/user_guide_src/source/libraries/user_agent.rst index 1b6a2988a..517382a65 100644 --- a/user_guide_src/source/libraries/user_agent.rst +++ b/user_guide_src/source/libraries/user_agent.rst @@ -76,8 +76,9 @@ Class Reference .. method:: is_browser([$key = NULL]) - :param string $key: optional browser name - :returns: bool + :param string $key: Optional browser name + :returns: TRUE if the user agent is a (specified) browser, FALSE if not + :rtype: bool Returns TRUE/FALSE (boolean) if the user agent is a known web browser. :: @@ -97,8 +98,9 @@ Class Reference .. method:: is_mobile([$key = NULL]) - :param string $key: optional mobile device name - :returns: bool + :param string $key: Optional mobile device name + :returns: TRUE if the user agent is a (specified) mobile device, FALSE if not + :rtype: bool Returns TRUE/FALSE (boolean) if the user agent is a known mobile device. :: @@ -118,8 +120,9 @@ Class Reference .. method:: is_robot([$key = NULL]) - :param string $key: optional robot name - :returns: bool + :param string $key: Optional robot name + :returns: TRUE if the user agent is a (specified) robot, FALSE if not + :rtype: bool Returns TRUE/FALSE (boolean) if the user agent is a known robot. @@ -130,43 +133,50 @@ Class Reference .. method:: is_referral() - :returns: bool + :returns: TRUE if the user agent is a referral, FALSE if not + :rtype: bool Returns TRUE/FALSE (boolean) if the user agent was referred from another site. .. method:: browser() - :returns: string + :returns: Detected browser or an empty string + :rtype: string Returns a string containing the name of the web browser viewing your site. .. method:: version() - :returns: string + :returns: Detected browser version or an empty string + :rtype: string Returns a string containing the version number of the web browser viewing your site. .. method:: mobile() - :returns: string + :returns: Detected mobile device brand or an empty string + :rtype: string Returns a string containing the name of the mobile device viewing your site. .. method:: robot() - :returns: string + :returns: Detected robot name or an empty string + :rtype: string Returns a string containing the name of the robot viewing your site. .. method:: platform() - :returns: string + :returns: Detected operating system or an empty string + :rtype: string Returns a string containing the platform viewing your site (Linux, Windows, OS X, etc.). .. method:: referrer() - :returns: string + :returns: Detected referrer or an empty string + :rtype: string The referrer, if the user agent was referred from another site. Typically you'll test for this as follows:: @@ -177,7 +187,8 @@ Class Reference .. method:: agent_string() - :returns: string + :returns: Full user agent string or an empty string + :rtype: string Returns a string containing the full user agent string. Typically it will be something like this:: @@ -185,8 +196,9 @@ Class Reference .. method:: accept_lang([$lang = 'en']) - :param string $lang: language key - :returns: bool + :param string $lang: Language key + :returns: TRUE if provided language is accepted, FALSE if not + :rtype: bool Lets you determine if the user agent accepts a particular language. Example:: @@ -200,14 +212,16 @@ Class Reference .. method:: languages() - :returns: array + :returns: An array list of accepted languages + :rtype: array Returns an array of languages supported by the user agent. .. method:: accept_charset([$charset = 'utf-8']) - :param string $charset: character set - :returns: bool + :param string $charset: Character set + :returns: TRUE if the character set is accepted, FALSE if not + :rtype: bool Lets you determine if the user agent accepts a particular character set. Example:: @@ -221,13 +235,14 @@ Class Reference .. method:: charsets() - :returns: array + :returns: An array list of accepted character sets + :rtype: array Returns an array of character sets accepted by the user agent. .. method:: parse($string) - :param string $string: A custom user-agent string - :returns: void + :param string $string: A custom user-agent string + :rtype: void Parses a custom user-agent string, different from the one reported by the current visitor.
\ No newline at end of file diff --git a/user_guide_src/source/libraries/xmlrpc.rst b/user_guide_src/source/libraries/xmlrpc.rst index d9b2dfb1a..2cf548750 100644 --- a/user_guide_src/source/libraries/xmlrpc.rst +++ b/user_guide_src/source/libraries/xmlrpc.rst @@ -459,18 +459,18 @@ Class Reference .. method:: initialize([$config = array()]) - :param array $config: configuration data - :returns: void + :param array $config: Configuration data + :rtype: void Initializes the XML-RPC library. Accepts an associative array containing your settings. .. method:: server($url[, $port = 80[, $proxy = FALSE[, $proxy_port = 8080]]]) - :param string $url: XML-RPC server URL - :param int $port: server port - :param string $proxy: optional proxy - :param int $proxy_port: proxy listening port - :returns: void + :param string $url: XML-RPC server URL + :param int $port: Server port + :param string $proxy: Optional proxy + :param int $proxy_port: Proxy listening port + :rtype: void Sets the URL and port number of the server to which a request is to be sent:: @@ -482,8 +482,8 @@ Class Reference .. method:: timeout($seconds = 5) - :param int $seconds: timeout in seconds - :returns: void + :param int $seconds: Timeout in seconds + :rtype: void Set a time out period (in seconds) after which the request will be canceled:: @@ -491,8 +491,8 @@ Class Reference .. method:: method($function) - :param string $function: method name - :returns: void + :param string $function: Method name + :rtype: void Sets the method that will be requested from the XML-RPC server:: @@ -502,8 +502,8 @@ Class Reference .. method:: request($incoming) - :param array $incoming: request data - :returns: void + :param array $incoming: Request data + :rtype: void Takes an array of data and builds request to be sent to XML-RPC server:: @@ -512,20 +512,22 @@ Class Reference .. method:: send_request() - :returns: bool + :returns: TRUE on success, FALSE on failure + :rtype: bool The request sending method. Returns boolean TRUE or FALSE based on success for failure, enabling it to be used conditionally. .. method set_debug($flag = TRUE) - :param bool $flag: debug status flag - :returns: void + :param bool $flag: Debug status flag + :rtype: void Enables or disables debugging, which will display a variety of information and error data helpful during development. .. method:: display_error() - :returns: string + :returns: Error message string + :rtype: string Returns an error message as a string if your request failed for some reason. :: @@ -534,7 +536,8 @@ Class Reference .. method:: display_response() - :returns: mixed + :returns: Response + :rtype: mixed Returns the response from the remote server once request is received. The response will typically be an associative array. :: @@ -543,9 +546,10 @@ Class Reference .. method:: send_error_message($number, $message) - :param int $number: error number - :param string $message: error message - :returns: object + :param int $number: Error number + :param string $message: Error message + :returns: XML_RPC_Response instance + :rtype: XML_RPC_Response This method lets you send an error message from your server to the client. First parameter is the error number while the second parameter is the error message. @@ -555,8 +559,9 @@ Class Reference .. method send_response($response) - :param array $response: response data - :returns: object + :param array $response: Response data + :returns: XML_RPC_Response instance + :rtype: XML_RPC_Response Lets you send the response from your server to the client. An array of valid data values must be sent with this method. :: @@ -569,4 +574,4 @@ Class Reference 'struct' ); - return $this->xmlrpc->send_response($response); + return $this->xmlrpc->send_response($response);
\ No newline at end of file diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index 535aa82d9..5ff7d07d6 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -54,9 +54,9 @@ Class Reference .. method:: add_data($filepath[, $data = NULL]) - :param mixed $filepath: a single file path or an array of file => data pairs - :param array $data: single file contents - :returns: void + :param mixed $filepath: A single file path or an array of file => data pairs + :param array $data: File contents (ignored if $filepath is an array) + :rtype: void Adds data to the Zip archive. Can work both in single and multiple files mode. @@ -90,8 +90,8 @@ Class Reference .. method:: add_dir($directory) - :param mixed $directory: string directory name or an array of multiple directories - :returns: void + :param mixed $directory: Directory name string or an array of multiple directories + :rtype: void Permits you to add a directory. Usually this method is unnecessary since you can place your data into directories when using ``$this->zip->add_data()``, but if you would like to create an empty directory you can do so:: @@ -100,9 +100,10 @@ Class Reference .. method:: read_file($path[, $archive_filepath = FALSE]) - :param string $path: Path to file - :param mixed $archive_filepath: New file name/path (string) or (boolean) whether to maintain the original filepath - :returns: bool + :param string $path: Path to file + :param mixed $archive_filepath: New file name/path (string) or (boolean) whether to maintain the original filepath + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to compress a file that already exists somewhere on your server. Supply a file path and the zip class will read it and add it to the archive:: @@ -138,10 +139,11 @@ Class Reference .. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]]) - :param string $path: path to directory - :param bool $preserve_filepath: whether to maintain the original path - :param string $root_path: part of the path to exclude from the archive directory - :returns: bool + :param string $path: Path to directory + :param bool $preserve_filepath: Whether to maintain the original path + :param string $root_path: Part of the path to exclude from the archive directory + :returns: TRUE on success, FALSE on failure + :rtype: bool Permits you to compress a directory (and its contents) that already exists somewhere on your server. Supply a path to the directory and the zip class will recursively read and recreate it as a Zip archive. @@ -166,8 +168,9 @@ Class Reference .. method:: archive($filepath) - :param string $filepath: path to target zip archive - :returns: bool + :param string $filepath: Path to target zip archive + :returns: TRUE on success, FALSE on failure + :rtype: bool Writes the Zip-encoded file to a directory on your server. Submit a valid server path ending in the file name. Make sure the directory is writable (660 or 666 is usually OK). Example:: @@ -176,8 +179,8 @@ Class Reference .. method:: download($filename = 'backup.zip') - :param string $filename: the archive file name - :returns: void + :param string $filename: Archive file name + :rtype: void Causes the Zip file to be downloaded from your server. You must pass the name you would like the zip file called. Example:: @@ -189,7 +192,8 @@ Class Reference .. method:: get_zip() - :returns: string + :returns: Zip file content + :rtype: string Returns the Zip-compressed file data. Generally you will not need this method unless you want to do something unique with the data. Example:: @@ -202,7 +206,7 @@ Class Reference .. method:: clear_data() - :returns: void + :rtype: void The Zip class caches your zip data so that it doesn't need to recompile the Zip archive for each method you use above. If, however, you need to create multiple Zip archives, each with different data, you can clear the cache between calls. Example:: |