Issue #1347914 by Albert Volkman, Lars Toomre, batigolix, NROTC_Webmaster, xjm, sven.lauer: Fix up API docs for Filter module

5 files changed, 308 insertions, 116 deletions

diff --git a/modules/filter/filter.admin.inc b/modules/filter/filter.admin.inc
index 5a21e6e2e..60284d993 100644
--- a/modules/filter/filter.admin.inc
+++ b/modules/filter/filter.admin.inc
@@ -2,13 +2,14 @@
 
 /**
  * @file
- * Admin page callbacks for the filter module.
+ * Administrative page callbacks for the Filter module.
  */
 
 /**
- * Menu callback; Displays a list of all text formats and allows them to be rearranged.
+ * Page callback: Form constructor for a form to list and reorder text formats.
  *
  * @ingroup forms
+ * @see filter_menu()
  * @see filter_admin_overview_submit()
  */
 function filter_admin_overview($form) {
@@ -45,6 +46,9 @@ function filter_admin_overview($form) {
   return $form;
 }
 
+/**
+ * Form submission handler for filter_admin_overview().
+ */
 function filter_admin_overview_submit($form, &$form_state) {
   foreach ($form_state['values']['formats'] as $id => $data) {
     if (is_array($data) && isset($data['weight'])) {
@@ -95,7 +99,26 @@ function theme_filter_admin_overview($variables) {
 }
 
 /**
- * Menu callback; Display a text format form.
+ * Page callback: Displays the text format add/edit form.
+ *
+ * @param object|null $format
+ *   (optional) An object representing a format, with the following properties:
+ *   - format: A machine-readable name representing the ID of the text format
+ *     to save. If this corresponds to an existing text format, that format
+ *     will be updated; otherwise, a new format will be created.
+ *   - name: The title of the text format.
+ *   - cache: (optional) An integer indicating whether the text format is
+ *     cacheable (1) or not (0). Defaults to 1.
+ *   - status: (optional) An integer indicating whether the text format is
+ *     enabled (1) or not (0). Defaults to 1.
+ *   - weight: (optional) The weight of the text format, which controls its
+ *     placement in text format lists. If omitted, the weight is set to 0.
+ *     Defaults to NULL.
+ *
+ * @return
+ *   A form array.
+ *
+ * @see filter_menu()
  */
 function filter_admin_format_page($format = NULL) {
   if (!isset($format->name)) {
@@ -109,11 +132,24 @@ function filter_admin_format_page($format = NULL) {
 }
 
 /**
- * Generate a text format form.
+ * Form constructor for the text format add/edit form.
+ *
+ * @param $format
+ *   A format object having the properties:
+ *   - format: A machine-readable name representing the ID of the text format to
+ *     save. If this corresponds to an existing text format, that format will be
+ *     updated; otherwise, a new format will be created.
+ *   - name: The title of the text format.
+ *   - cache: An integer indicating whether the text format is cacheable (1) or
+ *     not (0). Defaults to 1.
+ *   - status: (optional) An integer indicating whether the text format is
+ *     enabled (1) or not (0). Defaults to 1.
+ *   - weight: (optional) The weight of the text format, which controls its
+ *     placement in text format lists. If omitted, the weight is set to 0.
  *
- * @ingroup forms
  * @see filter_admin_format_form_validate()
  * @see filter_admin_format_form_submit()
+ * @ingroup forms
  */
 function filter_admin_format_form($form, &$form_state, $format) {
   $is_fallback = ($format->format == filter_fallback_format());
@@ -287,7 +323,9 @@ function theme_filter_admin_format_filter_order($variables) {
 }
 
 /**
- * Validate text format form submissions.
+ * Form validation handler for filter_admin_format_form().
+ *
+ * @see filter_admin_format_form_submit()
  */
 function filter_admin_format_form_validate($form, &$form_state) {
   $format_format = trim($form_state['values']['format']);
@@ -304,7 +342,9 @@ function filter_admin_format_form_validate($form, &$form_state) {
 }
 
 /**
- * Process text format form submissions.
+ * Form submission handler for filter_admin_format_form().
+ *
+ * @see filter_admin_format_form_validate()
  */
 function filter_admin_format_form_submit($form, &$form_state) {
   // Remove unnecessary values.
@@ -336,10 +376,14 @@ function filter_admin_format_form_submit($form, &$form_state) {
 }
 
 /**
- * Menu callback; confirm deletion of a format.
+ * Form constructor for the text format deletion confirmation form.
  *
- * @ingroup forms
+ * @param $format
+ *   An object representing a text format.
+ *
+ * @see filter_menu()
  * @see filter_admin_disable_submit()
+ * @ingroup forms
  */
 function filter_admin_disable($form, &$form_state, $format) {
   $form['#format'] = $format;
@@ -353,7 +397,7 @@ function filter_admin_disable($form, &$form_state, $format) {
 }
 
 /**
- * Process filter disable form submission.
+ * Form submission handler for filter_admin_disable().
  */
 function filter_admin_disable_submit($form, &$form_state) {
   $format = $form['#format'];
@@ -362,4 +406,3 @@ function filter_admin_disable_submit($form, &$form_state) {
 
   $form_state['redirect'] = 'admin/config/content/formats';
 }
-
diff --git a/modules/filter/filter.install b/modules/filter/filter.install
index 9d17eb54b..71ba97b08 100644
--- a/modules/filter/filter.install
+++ b/modules/filter/filter.install
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the filter module.
+ * Install, update, and uninstall functions for the Filter module.
  */
 
 /**
diff --git a/modules/filter/filter.module b/modules/filter/filter.module
index 7b451b7e3..182033fe8 100644
--- a/modules/filter/filter.module
+++ b/modules/filter/filter.module
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Framework for handling filtering of content.
+ * Framework for handling the filtering of content.
  */
 
 /**
@@ -71,6 +71,7 @@ function filter_theme() {
  * Implements hook_element_info().
  *
  * @see filter_process_format()
+ * @see text_format_wrapper()
  */
 function filter_element_info() {
   $type['text_format'] = array(
@@ -132,13 +133,16 @@ function filter_menu() {
 }
 
 /**
- * Access callback for deleting text formats.
+ * Access callback: Checks access for disabling text formats.
  *
  * @param $format
  *   A text format object.
+ *
  * @return
  *   TRUE if the text format can be disabled by the current user, FALSE
  *   otherwise.
+ *
+ * @see filter_menu()
  */
 function _filter_disable_format_access($format) {
   // The fallback format can never be disabled.
@@ -146,7 +150,7 @@ function _filter_disable_format_access($format) {
 }
 
 /**
- * Load a text format object from the database.
+ * Loads a text format object from the database.
  *
  * @param $format_id
  *   The format ID.
@@ -164,29 +168,32 @@ function filter_format_load($format_id) {
 }
 
 /**
- * Save a text format object to the database.
+ * Saves a text format object to the database.
  *
  * @param $format
- *   A format object using the properties:
- *   - 'format': A machine-readable name representing the ID of the text format
+ *   A format object having the properties:
+ *   - format: A machine-readable name representing the ID of the text format
  *     to save. If this corresponds to an existing text format, that format
  *     will be updated; otherwise, a new format will be created.
- *   - 'name': The title of the text format.
- *   - 'status': (optional) An integer indicating whether the text format is
+ *   - name: The title of the text format.
+ *   - status: (optional) An integer indicating whether the text format is
  *     enabled (1) or not (0). Defaults to 1.
- *   - 'weight': (optional) The weight of the text format, which controls its
+ *   - weight: (optional) The weight of the text format, which controls its
  *     placement in text format lists. If omitted, the weight is set to 0.
- *   - 'filters': (optional) An associative, multi-dimensional array of filters
+ *   - filters: (optional) An associative, multi-dimensional array of filters
  *     assigned to the text format, keyed by the name of each filter and using
  *     the properties:
- *     - 'weight': (optional) The weight of the filter in the text format. If
+ *     - weight: (optional) The weight of the filter in the text format. If
  *       omitted, either the currently stored weight is retained (if there is
  *       one), or the filter is assigned a weight of 10, which will usually
  *       put it at the bottom of the list.
- *     - 'status': (optional) A boolean indicating whether the filter is
+ *     - status: (optional) A boolean indicating whether the filter is
  *       enabled in the text format. If omitted, the filter will be disabled.
- *     - 'settings': (optional) An array of configured settings for the filter.
+ *     - settings: (optional) An array of configured settings for the filter.
  *       See hook_filter_info() for details.
+ *
+ * @return
+ *   SAVED_NEW or SAVED_UPDATED.
  */
 function filter_format_save($format) {
   $format->name = trim($format->name);
@@ -271,7 +278,7 @@ function filter_format_save($format) {
 }
 
 /**
- * Disable a text format.
+ * Disables a text format.
  *
  * There is no core facility to re-enable a disabled format. It is not deleted
  * to keep information for contrib and to make sure the format ID is never
@@ -313,7 +320,15 @@ function filter_format_exists($format_id) {
 }
 
 /**
- * Display a text format form title.
+ * Displays a text format form title.
+ *
+ * @param object $format
+ *   A format object.
+ *
+ * @return string
+ *   The name of the format.
+ *
+ * @see filter_menu()
  */
 function filter_admin_format_title($format) {
   return $format->name;
@@ -350,6 +365,7 @@ function filter_permission() {
  *
  * @param $format
  *   An object representing a text format.
+ *
  * @return
  *   The machine-readable permission name, or FALSE if the provided text format
  *   is malformed or is the fallback format (which is available to all users).
@@ -380,11 +396,13 @@ function filter_modules_disabled($modules) {
 }
 
 /**
- * Retrieve a list of text formats, ordered by weight.
+ * Retrieves a list of text formats, ordered by weight.
  *
  * @param $account
  *   (optional) If provided, only those formats that are allowed for this user
- *   account will be returned. All formats will be returned otherwise.
+ *   account will be returned. All formats will be returned otherwise. Defaults
+ *   to NULL.
+ *
  * @return
  *   An array of text format objects, keyed by the format ID and ordered by
  *   weight.
@@ -427,7 +445,7 @@ function filter_formats($account = NULL) {
 }
 
 /**
- * Resets text format caches.
+ * Resets the text format caches.
  *
  * @see filter_formats()
  */
@@ -443,6 +461,7 @@ function filter_formats_reset() {
  *
  * @param $format
  *   An object representing the text format.
+ *
  * @return
  *   An array of role names, keyed by role ID.
  */
@@ -461,6 +480,7 @@ function filter_get_roles_by_format($format) {
  *
  * @param $rid
  *   The user role ID to retrieve text formats for.
+ *
  * @return
  *   An array of text format objects that are allowed for the role, keyed by
  *   the text format ID and ordered by weight.
@@ -494,7 +514,8 @@ function filter_get_formats_by_role($rid) {
  *
  * @param $account
  *   (optional) The user account to check. Defaults to the currently logged-in
- *   user.
+ *   user. Defaults to NULL.
+ *
  * @return
  *   The ID of the user's default text format.
  *
@@ -525,15 +546,18 @@ function filter_default_format($account = NULL) {
  * format is initialized to output plain text. Installation profiles and site
  * administrators have the freedom to configure it further.
  *
- * Note that the fallback format is completely distinct from the default
- * format, which differs per user and is simply the first format which that
- * user has access to. The default and fallback formats are only guaranteed to
- * be the same for users who do not have access to any other format; otherwise,
- * the fallback format's weight determines its placement with respect to the
- * user's other formats.
+ * Note that the fallback format is completely distinct from the default format,
+ * which differs per user and is simply the first format which that user has
+ * access to. The default and fallback formats are only guaranteed to be the
+ * same for users who do not have access to any other format; otherwise, the
+ * fallback format's weight determines its placement with respect to the user's
+ * other formats.
  *
- * Any modules implementing a format deletion functionality must not delete
- * this format.
+ * Any modules implementing a format deletion functionality must not delete this
+ * format.
+ *
+ * @return
+ *   The ID of the fallback text format.
  *
  * @see hook_filter_format_disable()
  * @see filter_default_format()
@@ -550,6 +574,9 @@ function filter_fallback_format() {
 
 /**
  * Returns the title of the fallback text format.
+ *
+ * @return string
+ *   The title of the fallback text format.
  */
 function filter_fallback_format_title() {
   $fallback_format = filter_format_load(filter_fallback_format());
@@ -557,7 +584,10 @@ function filter_fallback_format_title() {
 }
 
 /**
- * Return a list of all filters provided by modules.
+ * Returns a list of all filters provided by modules.
+ *
+ * @return array
+ *   An array of filter formats.
  */
 function filter_get_filters() {
   $filters = &drupal_static(__FUNCTION__, array());
@@ -588,14 +618,16 @@ function filter_get_filters() {
 }
 
 /**
- * Helper function for sorting the filter list by filter name.
+ * Sorts an array of filters by filter name.
+ *
+ * Callback for uasort() within filter_get_filters().
  */
 function _filter_list_cmp($a, $b) {
   return strcmp($a['title'], $b['title']);
 }
 
 /**
- * Check if text in a certain text format is allowed to be cached.
+ * Checks if the text in a certain text format is allowed to be cached.
  *
  * This function can be used to check whether the result of the filtering
  * process can be cached. A text format may allow caching depending on the
@@ -603,6 +635,7 @@ function _filter_list_cmp($a, $b) {
  *
  * @param $format_id
  *   The text format ID to check.
+ *
  * @return
  *   TRUE if the given text format allows caching, FALSE otherwise.
  */
@@ -619,6 +652,7 @@ function filter_format_allowcache($format_id) {
  *
  * @param $format
  *   The text format object to check.
+ *
  * @return
  *   TRUE if all the filters enabled in the given text format allow caching,
  *   FALSE otherwise.
@@ -640,7 +674,7 @@ function _filter_format_is_cacheable($format) {
 }
 
 /**
- * Retrieve a list of filters for a given text format.
+ * Retrieves a list of filters for a given text format.
  *
  * Note that this function returns all associated filters regardless of whether
  * they are enabled or disabled. All functions working with the filter
@@ -694,7 +728,7 @@ function filter_list_format($format_id) {
 }
 
 /**
- * Run all the enabled filters on a piece of text.
+ * Runs all the enabled filters on a piece of text.
  *
  * Note: Because filters can inject JavaScript or execute PHP code, security is
  * vital here. When a user supplies a text format, you should validate it using
@@ -705,16 +739,20 @@ function filter_list_format($format_id) {
  * @param $text
  *   The text to be filtered.
  * @param $format_id
- *   The format id of the text to be filtered. If no format is assigned, the
- *   fallback format will be used.
+ *   (optional) The format ID of the text to be filtered. If no format is
+ *   assigned, the fallback format will be used. Defaults to NULL.
  * @param $langcode
- *   Optional: the language code of the text to be filtered, e.g. 'en' for
+ *   (optional) The language code of the text to be filtered, e.g. 'en' for
  *   English. This allows filters to be language aware so language specific
- *   text replacement can be implemented.
+ *   text replacement can be implemented. Defaults to an empty string.
  * @param $cache
- *   Boolean whether to cache the filtered output in the {cache_filter} table.
- *   The caller may set this to FALSE when the output is already cached
- *   elsewhere to avoid duplicate cache lookups and storage.
+ *   (optional) A Boolean indicating whether to cache the filtered output in the
+ *   {cache_filter} table. The caller may set this to FALSE when the output is
+ *   already cached elsewhere to avoid duplicate cache lookups and storage.
+ *   Defaults to FALSE.
+ *
+ * @return
+ *   The filtered text.
  *
  * @ingroup sanitization
  */
@@ -784,8 +822,8 @@ function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE)
  *   the text format id specified in #format or the user's default format by
  *   default, if NULL.
  *
- * The resulting value for the element will be an array holding the value and the
- * format.  For example, the value for the body element will be:
+ * The resulting value for the element will be an array holding the value and
+ * the format. For example, the value for the body element will be:
  * @code
  *   $form_state['values']['body']['value'] = 'foo';
  *   $form_state['values']['body']['format'] = 'foo';
@@ -795,7 +833,7 @@ function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE)
  *   The form element to process. Properties used:
  *   - #base_type: The form element #type to use for the 'value' element.
  *     'textarea' by default.
- *   - #format: (optional) The text format id to preselect. If NULL or not set,
+ *   - #format: (optional) The text format ID to preselect. If NULL or not set,
  *     the default format for the current user will be used.
  *
  * @return
@@ -933,7 +971,7 @@ function filter_process_format($element) {
 }
 
 /**
- * #pre_render callback for #type 'text_format' to hide field value from prying eyes.
+ * Render API callback: Hides the field value of 'text_format' elements.
  *
  * To not break form processing and previews if a user does not have access to a
  * stored text format, the expanded form elements in filter_process_format() are
@@ -976,7 +1014,7 @@ function theme_text_format_wrapper($variables) {
  *   An object representing the text format.
  * @param $account
  *   (optional) The user account to check access for; if omitted, the currently
- *   logged-in user is used.
+ *   logged-in user is used. Defaults to NULL.
  *
  * @return
  *   Boolean TRUE if the user is allowed to access the given format.
@@ -998,7 +1036,20 @@ function filter_access($format, $account = NULL) {
 }
 
 /**
- * Helper function for fetching filter tips.
+ * Retrieves the filter tips.
+ *
+ * @param $format_id
+ *   The ID of the text format for which to retrieve tips, or -1 to return tips
+ *   for all formats accessible to the current user.
+ * @param $long
+ *   (optional) Boolean indicating whether the long form of tips should be
+ *   returned. Defaults to FALSE.
+ *
+ * @return
+ *   An associative array of filtering tips, keyed by filter name. Each
+ *   filtering tip is an associative array with elements:
+ *   - tip: Tip text.
+ *   - id: Filter ID.
  */
 function _filter_tips($format_id, $long = FALSE) {
   global $user;
@@ -1032,14 +1083,14 @@ function _filter_tips($format_id, $long = FALSE) {
 /**
  * Parses an HTML snippet and returns it as a DOM object.
  *
- * This function loads the body part of a partial (X)HTML document
- * and returns a full DOMDocument object that represents this document.
- * You can use filter_dom_serialize() to serialize this DOMDocument
- * back to a XHTML snippet.
+ * This function loads the body part of a partial (X)HTML document and returns
+ * a full DOMDocument object that represents this document. You can use
+ * filter_dom_serialize() to serialize this DOMDocument back to a XHTML
+ * snippet.
  *
  * @param $text
- *   The partial (X)HTML snippet to load. Invalid mark-up
- *   will be corrected on import.
+ *   The partial (X)HTML snippet to load. Invalid mark-up will be corrected on
+ *   import.
  * @return
  *   A DOMDocument that represents the loaded (X)HTML snippet.
  */
@@ -1054,15 +1105,14 @@ function filter_dom_load($text) {
 /**
  * Converts a DOM object back to an HTML snippet.
  *
- * The function serializes the body part of a DOMDocument
- * back to an XHTML snippet.
- *
- * The resulting XHTML snippet will be properly formatted
- * to be compatible with HTML user agents.
+ * The function serializes the body part of a DOMDocument back to an XHTML
+ * snippet. The resulting XHTML snippet will be properly formatted to be
+ * compatible with HTML user agents.
  *
  * @param $dom_document
  *   A DOMDocument object to serialize, only the tags below
  *   the first <body> node will be converted.
+ *
  * @return
  *   A valid (X)HTML snippet, as a string.
  */
@@ -1099,9 +1149,11 @@ function filter_dom_serialize($dom_document) {
  * @param $dom_element
  *   The element potentially containing a CDATA node.
  * @param $comment_start
- *   String to use as a comment start marker to escape the CDATA declaration.
+ *   (optional) A string to use as a comment start marker to escape the CDATA
+ *   declaration. Defaults to '//'.
  * @param $comment_end
- *   String to use as a comment end marker to escape the CDATA declaration.
+ *   (optional) A string to use as a comment end marker to escape the CDATA
+ *   declaration. Defaults to an empty string.
  */
 function filter_dom_serialize_escape_cdata_element($dom_document, $dom_element, $comment_start = '//', $comment_end = '') {
   foreach ($dom_element->childNodes as $node) {
@@ -1156,7 +1208,7 @@ function theme_filter_guidelines($variables) {
 /**
  * @defgroup standard_filters Standard filters
  * @{
- * Filters implemented by the filter.module.
+ * Filters implemented by the Filter module.
  */
 
 /**
@@ -1204,7 +1256,10 @@ function filter_filter_info() {
 }
 
 /**
- * Settings callback for the HTML filter.
+ * Filter settings callback for the HTML content filter.
+ *
+ * See hook_filter_FILTER_settings() for documentation of parameters and return
+ * value.
  */
 function _filter_html_settings($form, &$form_state, $filter, $format, $defaults) {
   $filter->settings += $defaults;
@@ -1230,7 +1285,7 @@ function _filter_html_settings($form, &$form_state, $filter, $format, $defaults)
 }
 
 /**
- * HTML filter. Provides filtering of input into accepted HTML.
+ * Provides filtering of input into accepted HTML.
  */
 function _filter_html($text, $filter) {
   $allowed_tags = preg_split('/\s+|<|>/', $filter->settings['allowed_html'], -1, PREG_SPLIT_NO_EMPTY);
@@ -1249,7 +1304,9 @@ function _filter_html($text, $filter) {
 }
 
 /**
- * Filter tips callback for HTML filter.
+ * Filter tips callback: Provides help for the HTML filter.
+ *
+ * @see filter_filter_info()
  */
 function _filter_html_tips($filter, $format, $long = FALSE) {
   global $base_url;
@@ -1347,7 +1404,9 @@ function _filter_html_tips($filter, $format, $long = FALSE) {
 }
 
 /**
- * Settings callback for URL filter.
+ * Filter URL settings callback: Provides settings for the URL filter.
+ *
+ * @see filter_filter_info()
  */
 function _filter_url_settings($form, &$form_state, $filter, $format, $defaults) {
   $filter->settings += $defaults;
@@ -1366,7 +1425,7 @@ function _filter_url_settings($form, &$form_state, $filter, $format, $defaults)
 }
 
 /**
- * URL filter. Automatically converts text into hyperlinks.
+ * Converts text into hyperlinks automatically.
  *
  * This filter identifies and makes clickable three types of "links".
  * - URLs like http://example.com.
@@ -1489,7 +1548,9 @@ function _filter_url($text, $filter) {
 }
 
 /**
- * preg_replace callback to make links out of absolute URLs.
+ * Makes links out of absolute URLs.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
  */
 function _filter_url_parse_full_links($match) {
   // The $i:th parenthesis in the regexp contains the URL.
@@ -1502,7 +1563,9 @@ function _filter_url_parse_full_links($match) {
 }
 
 /**
- * preg_replace callback to make links out of e-mail addresses.
+ * Makes links out of e-mail addresses.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
  */
 function _filter_url_parse_email_links($match) {
   // The $i:th parenthesis in the regexp contains the URL.
@@ -1515,7 +1578,9 @@ function _filter_url_parse_email_links($match) {
 }
 
 /**
- * preg_replace callback to make links out of domain names starting with "www."
+ * Makes links out of domain names starting with "www."
+ *
+ * Callback for preg_replace_callback() within _filter_url().
  */
 function _filter_url_parse_partial_links($match) {
   // The $i:th parenthesis in the regexp contains the URL.
@@ -1528,14 +1593,17 @@ function _filter_url_parse_partial_links($match) {
 }
 
 /**
- * preg_replace callback to escape contents of HTML comments
+ * Escapes the contents of HTML comments.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
  *
  * @param $match
  *   An array containing matches to replace from preg_replace_callback(),
  *   whereas $match[1] is expected to contain the content to be filtered.
  * @param $escape
- *   (optional) Boolean whether to escape (TRUE) or unescape comments (FALSE).
- *   Defaults to neither. If TRUE, statically cached $comments are reset.
+ *   (optional) A Boolean indicating whether to escape (TRUE) or unescape
+ *   comments (FALSE). Defaults to NULL, indicating neither. If TRUE, statically
+ *   cached $comments are reset.
  */
 function _filter_url_escape_comments($match, $escape = NULL) {
   static $mode, $comments = array();
@@ -1582,21 +1650,24 @@ function _filter_url_trim($text, $length = NULL) {
 }
 
 /**
- * Filter tips callback for URL filter.
+ * Filter tips callback: Provides help for the URL filter.
+ *
+ * @see filter_filter_info()
  */
 function _filter_url_tips($filter, $format, $long = FALSE) {
   return t('Web page addresses and e-mail addresses turn into links automatically.');
 }
 
 /**
- * Scan input and make sure that all HTML tags are properly closed and nested.
+ * Scans the input and makes sure that HTML tags are properly closed.
  */
 function _filter_htmlcorrector($text) {
   return filter_dom_serialize(filter_dom_load($text));
 }
 
 /**
- * Convert line breaks into <p> and <br> in an intelligent fashion.
+ * Converts line breaks into <p> and <br> in an intelligent fashion.
+ *
  * Based on: http://photomatt.net/scripts/autop
  */
 function _filter_autop($text) {
@@ -1662,7 +1733,9 @@ function _filter_autop($text) {
 }
 
 /**
- * Filter tips callback for auto-paragraph filter.
+ * Filter tips callback: Provides help for the auto-paragraph filter.
+ *
+ * @see filter_filter_info()
  */
 function _filter_autop_tips($filter, $format, $long = FALSE) {
   if ($long) {
@@ -1681,7 +1754,9 @@ function _filter_html_escape($text) {
 }
 
 /**
- * Filter tips callback for HTML escaping filter.
+ * Filter tips callback: Provides help for the HTML escaping filter.
+ *
+ * @see filter_filter_info()
  */
 function _filter_html_escape_tips($filter, $format, $long = FALSE) {
   return t('No HTML tags allowed.');
diff --git a/modules/filter/filter.pages.inc b/modules/filter/filter.pages.inc
index dbbbe4c5a..50f81177f 100644
--- a/modules/filter/filter.pages.inc
+++ b/modules/filter/filter.pages.inc
@@ -2,12 +2,17 @@
 
 /**
  * @file
- * User page callbacks for the filter module.
+ * User page callbacks for the Filter module.
  */
 
-
 /**
- * Menu callback; show a page with long filter tips.
+ * Page callback: Displays a page with long filter tips.
+ *
+ * @return string
+ *   An HTML-formatted string.
+ *
+ * @see filter_menu()
+ * @see theme_filter_tips()
  */
 function filter_tips_long() {
   $format_id = arg(2);
@@ -20,13 +25,12 @@ function filter_tips_long() {
   return $output;
 }
 
-
 /**
  * Returns HTML for a set of filter tips.
  *
  * @param $variables
  *   An associative array containing:
- *   - tips: An array containing descriptions and a CSS id in the form of
+ *   - tips: An array containing descriptions and a CSS ID in the form of
  *     'module-name/filter-id' (only used when $long is TRUE) for each
  *     filter in one or more text formats. Example:
  *     @code
diff --git a/modules/filter/filter.test b/modules/filter/filter.test
index aa1693fba..0c3949517 100644
--- a/modules/filter/filter.test
+++ b/modules/filter/filter.test
@@ -22,7 +22,7 @@ class FilterCRUDTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test CRUD operations for text formats and filters.
+   * Tests CRUD operations for text formats and filters.
    */
   function testTextFormatCRUD() {
     // Add a text format with minimum data only.
@@ -73,7 +73,7 @@ class FilterCRUDTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Verify that a text format is properly stored.
+   * Verifies that a text format is properly stored.
    */
   function verifyTextFormat($format) {
     $t_args = array('%format' => $format->name);
@@ -111,7 +111,7 @@ class FilterCRUDTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Verify that filters are properly stored for a text format.
+   * Verifies that filters are properly stored for a text format.
    */
   function verifyFilters($format) {
     // Verify filter database records.
@@ -160,6 +160,9 @@ class FilterCRUDTestCase extends DrupalWebTestCase {
   }
 }
 
+/**
+ * Tests the administrative functionality of the Filter module.
+ */
 class FilterAdminTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(
@@ -185,6 +188,9 @@ class FilterAdminTestCase extends DrupalWebTestCase {
     $this->drupalLogin($this->admin_user);
   }
 
+  /**
+   * Tests the format administration functionality.
+   */
   function testFormatAdmin() {
     // Add text format.
     $this->drupalGet('admin/config/content/formats');
@@ -249,7 +255,7 @@ class FilterAdminTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test filter administration functionality.
+   * Tests filter administration functionality.
    */
   function testFilterAdmin() {
     // URL filter.
@@ -413,11 +419,43 @@ class FilterAdminTestCase extends DrupalWebTestCase {
   }
 }
 
+/**
+ * Tests the filter format access functionality in the Filter module.
+ */
 class FilterFormatAccessTestCase extends DrupalWebTestCase {
+  /**
+   * A user with administrative permissions.
+   *
+   * @var object
+   */
   protected $admin_user;
+
+  /**
+   * A user with 'administer filters' permission.
+   *
+   * @var object
+   */
   protected $filter_admin_user;
+
+  /**
+   * A user with permission to create and edit own content.
+   *
+   * @var object
+   */
   protected $web_user;
+
+  /**
+   * An object representing an allowed text format.
+   *
+   * @var object
+   */
   protected $allowed_format;
+
+  /**
+   * An object representing a disallowed text format.
+   *
+   * @var object
+   */
   protected $disallowed_format;
 
   public static function getInfo() {
@@ -471,6 +509,9 @@ class FilterFormatAccessTestCase extends DrupalWebTestCase {
     ));
   }
 
+  /**
+   * Tests the Filter format access permissions functionality.
+   */
   function testFormatPermissions() {
     // Make sure that a regular user only has access to the text format they
     // were granted access to, as well to the fallback format.
@@ -507,6 +548,9 @@ class FilterFormatAccessTestCase extends DrupalWebTestCase {
     $this->assertTrue(isset($options[filter_fallback_format()]), t('The fallback format appears as an option when adding a new node.'));
   }
 
+  /**
+   * Tests if text format is available to a role.
+   */
   function testFormatRoles() {
     // Get the role ID assigned to the regular user; it must be the maximum.
     $rid = max(array_keys($this->web_user->roles));
@@ -528,13 +572,13 @@ class FilterFormatAccessTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test editing a page using a disallowed text format.
+   * Tests editing a page using a disallowed text format.
    *
-   * Verifies that regular users and administrators are able to edit a page,
-   * but not allowed to change the fields which use an inaccessible text
-   * format. Also verifies that fields which use a text format that does not
-   * exist can be edited by administrators only, but that the administrator is
-   * forced to choose a new format before saving the page.
+   * Verifies that regular users and administrators are able to edit a page, but
+   * not allowed to change the fields which use an inaccessible text format.
+   * Also verifies that fields which use a text format that does not exist can
+   * be edited by administrators only, but that the administrator is forced to
+   * choose a new format before saving the page.
    */
   function testFormatWidgetPermissions() {
     $langcode = LANGUAGE_NONE;
@@ -650,7 +694,7 @@ class FilterFormatAccessTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Rebuild text format and permission caches in the thread running the tests.
+   * Rebuilds text format and permission caches in the thread running the tests.
    */
   protected function resetFilterCaches() {
     filter_formats_reset();
@@ -658,6 +702,9 @@ class FilterFormatAccessTestCase extends DrupalWebTestCase {
   }
 }
 
+/**
+ * Tests the default filter functionality in the Filter module.
+ */
 class FilterDefaultFormatTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(
@@ -667,6 +714,9 @@ class FilterDefaultFormatTestCase extends DrupalWebTestCase {
     );
   }
 
+  /**
+   * Tests if the default text format is accessible to users.
+   */
   function testDefaultTextFormats() {
     // Create two text formats, and two users. The first user has access to
     // both formats, but the second user only has access to the second one.
@@ -710,7 +760,7 @@ class FilterDefaultFormatTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Rebuild text format and permission caches in the thread running the tests.
+   * Rebuilds text format and permission caches in the thread running the tests.
    */
   protected function resetFilterCaches() {
     filter_formats_reset();
@@ -718,6 +768,9 @@ class FilterDefaultFormatTestCase extends DrupalWebTestCase {
   }
 }
 
+/**
+ * Tests the behavior of check_markup() when it is called without text format.
+ */
 class FilterNoFormatTestCase extends DrupalWebTestCase {
   public static function getInfo() {
     return array(
@@ -727,6 +780,12 @@ class FilterNoFormatTestCase extends DrupalWebTestCase {
     );
   }
 
+  /**
+   * Tests text without format.
+   *
+   * Tests if text with no format is filtered the same way as text in the
+   * fallback format.
+   */
   function testCheckMarkupNoFormat() {
     // Create some text. Include some HTML and line breaks, so we get a good
     // test of the filtering that is applied to it.
@@ -757,7 +816,10 @@ class FilterSecurityTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test that filtered content is emptied when an actively used filter module is disabled.
+   * Tests removal of filtered content when an active filter is disabled.
+   *
+   * Tests that filtered content is emptied when an actively used filter module
+   * is disabled.
    */
   function testDisableFilterModule() {
     // Create a new node.
@@ -800,7 +862,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
   }
 
   /**
-   * Test the line break filter.
+   * Tests the line break filter.
    */
   function testLineBreakFilter() {
     // Setup dummy filter object.
@@ -1060,7 +1122,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
   }
 
   /**
-   * Test filter settings, defaults, access restrictions and similar.
+   * Tests filter settings, defaults, access restrictions and similar.
    *
    * @todo This is for functions like filter_filter and check_markup, whose
    *   functionality is not completely focused on filtering. Some ideas:
@@ -1116,7 +1178,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
   }
 
   /**
-   * Test the spam deterrent.
+   * Tests the spam deterrent.
    */
   function testNoFollowFilter() {
     // Setup dummy filter object.
@@ -1147,7 +1209,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
   }
 
   /**
-   * Test the loose, admin HTML filter.
+   * Tests the loose, admin HTML filter.
    */
   function testFilterXSSAdmin() {
     // DRUPAL-SA-2008-044
@@ -1541,7 +1603,7 @@ www.example.com with a newline in comments -->
   }
 
   /**
-   * Test the HTML corrector filter.
+   * Tests the HTML corrector filter.
    *
    * @todo This test could really use some validity checking function.
    */
@@ -1745,9 +1807,9 @@ body {color:red}
    * @param $needle
    *   Lowercase, plain text to look for.
    * @param $message
-   *   Message to display if failed.
+   *   (optional) Message to display if failed. Defaults to an empty string.
    * @param $group
-   *   The group this message belongs to, defaults to 'Other'.
+   *   (optional) The group this message belongs to. Defaults to 'Other'.
    * @return
    *   TRUE on pass, FALSE on fail.
    */
@@ -1769,9 +1831,9 @@ body {color:red}
    * @param $needle
    *   Lowercase, plain text to look for.
    * @param $message
-   *   Message to display if failed.
+   *   (optional) Message to display if failed. Defaults to an empty string.
    * @param $group
-   *   The group this message belongs to, defaults to 'Other'.
+   *   (optional) The group this message belongs to. Defaults to 'Other'.
    * @return
    *   TRUE on pass, FALSE on fail.
    */
@@ -1781,7 +1843,7 @@ body {color:red}
 }
 
 /**
- * Tests for filter hook invocation.
+ * Tests for Filter's hook invocations.
  */
 class FilterHooksTestCase extends DrupalWebTestCase {
   public static function getInfo() {
@@ -1799,7 +1861,10 @@ class FilterHooksTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test that hooks run correctly on creating, editing, and deleting a text format.
+   * Tests hooks on format management.
+   *
+   * Tests that hooks run correctly on creating, editing, and deleting a text
+   * format.
    */
   function testFilterHooks() {
     // Add a text format.
@@ -1846,6 +1911,11 @@ class FilterHooksTestCase extends DrupalWebTestCase {
  * Tests filter settings.
  */
 class FilterSettingsTestCase extends DrupalWebTestCase {
+  /**
+   * The installation profile to use with this test class.
+   *
+   * @var string
+   */
   protected $profile = 'testing';
 
   public static function getInfo() {