diff --git a/core/modules/filter/filter.admin.inc b/core/modules/filter/filter.admin.inc
index b4a7008..2b4e0a3 100644
--- a/core/modules/filter/filter.admin.inc
+++ b/core/modules/filter/filter.admin.inc
@@ -2,14 +2,15 @@
/**
* @file
- * Admin page callbacks for the filter module.
+ * Admin page callbacks for the Filter module.
*/
/**
- * Menu callback; Displays a list of all text formats and allows them to be rearranged.
+ * Form constructor for a form to list and reorder text formats.
*
- * @ingroup forms
+ * @see filter_menu()
* @see filter_admin_overview_submit()
+ * @ingroup forms
*/
function filter_admin_overview($form) {
// Overview of all formats.
@@ -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,9 @@ function theme_filter_admin_overview($variables) {
}
/**
- * Menu callback; Display a text format form.
+ * Page callback: Displays the text format add/edit form.
+ *
+ * @see filter_menu()
*/
function filter_admin_format_page($format = NULL) {
if (!isset($format->name)) {
@@ -109,11 +115,11 @@ function filter_admin_format_page($format = NULL) {
}
/**
- * Generate a text format form.
+ * Form constructor for the text format add/edit form.
*
- * @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 +293,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 +312,9 @@ function filter_admin_format_form_validate($form, &$form_state) {
}
/**
- * Process text format form submissions.
+ * Form submission hanlder 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 +346,11 @@ function filter_admin_format_form_submit($form, &$form_state) {
}
/**
- * Menu callback; confirm deletion of a format.
+ * Form constructor for text format deletion confirmation form.
*
- * @ingroup forms
+ * @see filter_menu()
* @see filter_admin_disable_submit()
+ * @ingroup forms
*/
function filter_admin_disable($form, &$form_state, $format) {
$form['#format'] = $format;
@@ -353,7 +364,7 @@ function filter_admin_disable($form, &$form_state, $format) {
}
/**
- * Process filter disable form submission.
+ * Form submission handler for filter_format_disable().
*/
function filter_admin_disable_submit($form, &$form_state) {
$format = $form['#format'];
diff --git a/core/modules/filter/filter.admin.js b/core/modules/filter/filter.admin.js
index 3bc6233..93b695a 100644
--- a/core/modules/filter/filter.admin.js
+++ b/core/modules/filter/filter.admin.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Attaches adminstration-specific behavior for the Filter module.
+ */
+
(function ($) {
Drupal.behaviors.filterStatus = {
diff --git a/core/modules/filter/filter.api.php b/core/modules/filter/filter.api.php
index 6675e4a..9f6300d 100644
--- a/core/modules/filter/filter.api.php
+++ b/core/modules/filter/filter.api.php
@@ -11,7 +11,7 @@
*/
/**
- * Define content filters.
+ * Defines content filters.
*
* User submitted content is passed through a group of filters before it is
* output in HTML, in order to remove insecure or unwanted parts, correct or
@@ -24,12 +24,12 @@
* input filters they provide.
*
* Filtering is a two-step process. First, the content is 'prepared' by calling
- * the 'prepare callback' function for every filter. The purpose of the 'prepare
- * callback' is to escape HTML-like structures. For example, imagine a filter
- * which allows the user to paste entire chunks of programming code without
- * requiring manual escaping of special HTML characters like < or &. If the
- * programming code were left untouched, then other filters could think it was
- * HTML and change it. For many filters, the prepare step is not necessary.
+ * the 'prepare callback' function for every filter. The purpose of the
+ * 'prepare callback' is to escape HTML-like structures. For example, imagine a
+ * filter which allows the user to paste entire chunks of programming code
+ * without requiring manual escaping of special HTML characters like < or &. If
+ * the programming code were left untouched, then other filters could think it
+ * was HTML and change it. For many filters, the prepare step is not necessary.
*
* The second step is the actual processing step. The result from passing the
* text through all the filters' prepare steps gets passed to all the filters
@@ -39,10 +39,10 @@
*
* For performance reasons content is only filtered once; the result is stored
* in the cache table and retrieved from the cache the next time the same piece
- * of content is displayed. If a filter's output is dynamic, it can override the
- * cache mechanism, but obviously this should be used with caution: having one
- * filter that does not support caching in a particular text format disables
- * caching for the entire format, not just for one filter.
+ * of content is displayed. If a filter's output is dynamic, it can override
+ * the cache mechanism, but obviously this should be used with caution: having
+ * one filter that does not support caching in a particular text format
+ * disables caching for the entire format, not just for one filter.
*
* Beware of the filter cache when developing your module: it is advised to set
* your filter to 'cache' => FALSE while developing, but be sure to remove that
@@ -56,8 +56,9 @@
* - title: (required) An administrative summary of what the filter does.
* - description: Additional administrative information about the filter's
* behavior, if needed for clarification.
- * - settings callback: The name of a function that returns configuration form
- * elements for the filter. See hook_filter_FILTER_settings() for details.
+ * - settings callback: The name of a function that returns configuration
+ * form elements for the filter. See hook_filter_FILTER_settings() for
+ * details.
* - default settings: An associative array containing default settings for
* the filter, to be applied when the filter has not been configured yet.
* - prepare callback: The name of a function that escapes the content before
@@ -69,9 +70,9 @@
* Note that setting this to FALSE makes the entire text format not
* cacheable, which may have an impact on the site's overall performance.
* See filter_format_allowcache() for details.
- * - tips callback: The name of a function that returns end-user-facing filter
- * usage guidelines for the filter. See hook_filter_FILTER_tips() for
- * details.
+ * - tips callback: The name of a function that returns end-user-facing
+ * filter usage guidelines for the filter. See hook_filter_FILTER_tips()
+ * for details.
* - weight: A default weight for the filter in new text formats.
*
* @see filter_example.module
@@ -100,7 +101,7 @@ function hook_filter_info() {
}
/**
- * Perform alterations on filter definitions.
+ * Performs alterations on filter definitions.
*
* @param $info
* Array of information on filters exposed by hook_filter_info()
@@ -276,7 +277,7 @@ function hook_filter_FILTER_tips($filter, $format, $long) {
*/
/**
- * Perform actions when a new text format has been created.
+ * Performs actions when a new text format has been created.
*
* @param $format
* The format object of the format being updated.
@@ -289,7 +290,7 @@ function hook_filter_format_insert($format) {
}
/**
- * Perform actions when a text format has been updated.
+ * Performs actions when a text format has been updated.
*
* This hook allows modules to act when a text format has been updated in any
* way. For example, when filters have been reconfigured, disabled, or
@@ -306,7 +307,7 @@ function hook_filter_format_update($format) {
}
/**
- * Perform actions when a text format has been disabled.
+ * Performs actions when a text format has been disabled.
*
* @param $format
* The format object of the format being disabled.
diff --git a/core/modules/filter/filter.css b/core/modules/filter/filter.css
index f731733..b826512 100644
--- a/core/modules/filter/filter.css
+++ b/core/modules/filter/filter.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Stylesheet for the Filter module.
+ */
.text-format-wrapper .form-item {
margin-bottom: 0;
diff --git a/core/modules/filter/filter.js b/core/modules/filter/filter.js
index c286159..4265387 100644
--- a/core/modules/filter/filter.js
+++ b/core/modules/filter/filter.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Attaches behavior for the Filter module.
+ */
+
(function ($) {
/**
diff --git a/core/modules/filter/filter.module b/core/modules/filter/filter.module
index 0747250..d4a1636 100644
--- a/core/modules/filter/filter.module
+++ b/core/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 deleting 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
+ * - 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);
@@ -269,7 +276,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
@@ -311,7 +318,9 @@ function filter_format_exists($format_id) {
}
/**
- * Display a text format form title.
+ * Title callback: Displays a text format form title.
+ *
+ * @see filter_menu()
*/
function filter_admin_format_title($format) {
return $format->name;
@@ -348,6 +357,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).
@@ -378,11 +388,12 @@ 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.
+ *
* @return
* An array of text format objects, keyed by the format ID and ordered by
* weight.
@@ -425,7 +436,7 @@ function filter_formats($account = NULL) {
}
/**
- * Resets text format caches.
+ * Resets the text format caches.
*
* @see filter_formats()
*/
@@ -441,6 +452,7 @@ function filter_formats_reset() {
*
* @param $format
* An object representing the text format.
+ *
* @return
* An array of role names, keyed by role ID.
*/
@@ -459,6 +471,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.
@@ -493,6 +506,7 @@ function filter_get_formats_by_role($rid) {
* @param $account
* (optional) The user account to check. Defaults to the currently logged-in
* user.
+ *
* @return
* The ID of the user's default text format.
*
@@ -533,6 +547,9 @@ function filter_default_format($account = NULL) {
* 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()
*/
@@ -555,7 +572,7 @@ function filter_fallback_format_title() {
}
/**
- * Return a list of all filters provided by modules.
+ * Returns a list of all filters provided by modules.
*/
function filter_get_filters() {
$filters = &drupal_static(__FUNCTION__, array());
@@ -586,14 +603,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
@@ -601,6 +620,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.
*/
@@ -610,13 +630,14 @@ function filter_format_allowcache($format_id) {
}
/**
- * Helper function to determine whether the output of a given text format can be cached.
+ * Determines whether the output of a given text format can be cached.
*
* The output of a given text format can be cached when all enabled filters in
* the text format allow caching.
*
* @param $format
* The text format object to check.
+ *
* @return
* TRUE if all the filters enabled in the given text format allow caching,
* FALSE otherwise.
@@ -638,7 +659,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
@@ -692,7 +713,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
@@ -714,6 +735,9 @@ function filter_list_format($format_id) {
* The caller may set this to FALSE when the output is already cached
* elsewhere to avoid duplicate cache lookups and storage.
*
+ * @return
+ * The filtered text.
+ *
* @ingroup sanitization
*/
function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE) {
@@ -782,8 +806,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';
@@ -931,11 +955,11 @@ 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
- * forced to take over the stored #default_values for 'value' and 'format'.
+ * 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 forced to take over the stored #default_values for 'value' and 'format'.
* However, to prevent the unfiltered, original #value from being displayed to
* the user, we replace it with a friendly notice here.
*
@@ -996,7 +1020,25 @@ 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 array, keyed by text format name. For each format, the value is another
+ * array keyed by filter name. The values of the inner arrays are arrays
+ * of the form:
+ * @code
+ * array(
+ * 'tip' => 'Tip text',
+ * 'id' => FILTER_ID
+ * )
+ * @endcode
*/
function _filter_tips($format_id, $long = FALSE) {
global $user;
@@ -1030,14 +1072,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.
*/
@@ -1052,15 +1094,16 @@ 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 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 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 node will be converted.
+ *
* @return
* A valid (X)HTML snippet, as a string.
*/
@@ -1123,7 +1166,7 @@ function filter_dom_serialize_escape_cdata_element($dom_document, $dom_element,
}
/**
- * Returns HTML for a link to the more extensive filter tips.
+ * Returns the HTML for a link to the more extensive filter tips.
*
* @ingroup themeable
*/
@@ -1132,7 +1175,7 @@ function theme_filter_tips_more_info() {
}
/**
- * Returns HTML for guidelines for a text format.
+ * Returns the HTML for guidelines for a text format.
*
* @param $variables
* An associative array containing:
@@ -1154,7 +1197,7 @@ function theme_filter_guidelines($variables) {
/**
* @defgroup standard_filters Standard filters
* @{
- * Filters implemented by the filter.module.
+ * Filters implemented by the Filter module.
*/
/**
@@ -1247,7 +1290,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;
@@ -1345,7 +1390,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;
@@ -1486,7 +1533,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.
@@ -1499,7 +1548,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.
@@ -1512,7 +1563,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.
@@ -1525,7 +1578,7 @@ function _filter_url_parse_partial_links($match) {
}
/**
- * preg_replace callback to escape contents of HTML comments
+ * Escapes the contents of HTML comments.
*
* @param $match
* An array containing matches to replace from preg_replace_callback(),
@@ -1533,6 +1586,8 @@ function _filter_url_parse_partial_links($match) {
* @param $escape
* (optional) Boolean whether to escape (TRUE) or unescape comments (FALSE).
* Defaults to neither. If TRUE, statically cached $comments are reset.
+ *
+ * Callback for preg_replace_callback() within _filter_url().
*/
function _filter_url_escape_comments($match, $escape = NULL) {
static $mode, $comments = array();
@@ -1579,21 +1634,23 @@ function _filter_url_trim($text, $length = NULL) {
}
/**
- * Filter tips callback for URL filter.
+ * Filter URL 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 and
in an intelligent fashion.
+ * Converts line breaks into
and
in an intelligent fashion.
* Based on: http://photomatt.net/scripts/autop
*/
function _filter_autop($text) {
@@ -1659,7 +1716,9 @@ function _filter_autop($text) {
}
/**
- * Filter tips callback for auto-paragraph filter.
+ * Filter autop tips callback: Provides help for the auto-paragraph filter.
+ *
+ * @see filter_filter_info()
*/
function _filter_autop_tips($filter, $format, $long = FALSE) {
if ($long) {
@@ -1678,7 +1737,9 @@ function _filter_html_escape($text) {
}
/**
- * Filter tips callback for HTML escaping filter.
+ * Filter HTML escape tips callback: Provides help for an 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/core/modules/filter/filter.pages.inc b/core/modules/filter/filter.pages.inc
index dbbbe4c..db72e31 100644
--- a/core/modules/filter/filter.pages.inc
+++ b/core/modules/filter/filter.pages.inc
@@ -2,12 +2,13 @@
/**
* @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.
+ *
+ * @see filter_menu()
*/
function filter_tips_long() {
$format_id = arg(2);
@@ -20,7 +21,6 @@ function filter_tips_long() {
return $output;
}
-
/**
* Returns HTML for a set of filter tips.
*
diff --git a/core/modules/filter/filter.test b/core/modules/filter/filter.test
index f6476f5..93a89e9 100644
--- a/core/modules/filter/filter.test
+++ b/core/modules/filter/filter.test
@@ -2,11 +2,11 @@
/**
* @file
- * Tests for filter.module.
+ * Tests for the Filter module.
*/
/**
- * Tests for text format and filter CRUD operations.
+ * Tests the text format and filter CRUD operations.
*/
class FilterCRUDTestCase extends DrupalWebTestCase {
public static function getInfo() {
@@ -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.
@@ -185,6 +185,9 @@ class FilterAdminTestCase extends DrupalWebTestCase {
$this->drupalLogin($this->admin_user);
}
+ /**
+ * Tests the text format adminstration functionality.
+ */
function testFormatAdmin() {
// Add text format.
$this->drupalGet('admin/config/content/formats');
@@ -249,7 +252,7 @@ class FilterAdminTestCase extends DrupalWebTestCase {
}
/**
- * Test filter administration functionality.
+ * Tests the filter administration functionality.
*/
function testFilterAdmin() {
// URL filter.
@@ -459,6 +462,9 @@ class FilterFormatAccessTestCase extends DrupalWebTestCase {
));
}
+ /**
+ * Tests the text format permission handling.
+ */
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.
@@ -495,6 +501,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 the text format role handling.
+ */
function testFormatRoles() {
// Get the role ID assigned to the regular user; it must be the maximum.
$rid = max(array_keys($this->web_user->roles));
@@ -516,7 +525,7 @@ 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
@@ -638,7 +647,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 test.
*/
protected function resetFilterCaches() {
filter_formats_reset();
@@ -655,6 +664,9 @@ class FilterDefaultFormatTestCase extends DrupalWebTestCase {
);
}
+ /**
+ * Tests default text format handling.
+ */
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.
@@ -698,7 +710,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 test.
*/
protected function resetFilterCaches() {
filter_formats_reset();
@@ -715,6 +727,9 @@ class FilterNoFormatTestCase extends DrupalWebTestCase {
);
}
+ /**
+ * Tests the fallback text 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.
@@ -727,7 +742,7 @@ class FilterNoFormatTestCase extends DrupalWebTestCase {
}
/**
- * Security tests for missing/vanished text formats or filters.
+ * Tests security aspects for missing/vanished text formats or filters.
*/
class FilterSecurityTestCase extends DrupalWebTestCase {
public static function getInfo() {
@@ -745,7 +760,7 @@ class FilterSecurityTestCase extends DrupalWebTestCase {
}
/**
- * Test that filtered content is emptied when an actively used filter module is disabled.
+ * Tests whehter filtered content is emptied when a the module is disabled.
*/
function testDisableFilterModule() {
// Create a new node.
@@ -776,7 +791,7 @@ class FilterSecurityTestCase extends DrupalWebTestCase {
}
/**
- * Unit tests for core filters.
+ * Tests core filters.
*/
class FilterUnitTestCase extends DrupalUnitTestCase {
public static function getInfo() {
@@ -788,7 +803,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
}
/**
- * Test the line break filter.
+ * Tests the line break filter.
*/
function testLineBreakFilter() {
// Setup dummy filter object.
@@ -1048,7 +1063,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
}
/**
- * Test filter settings, defaults, access restrictions and similar.
+ * Tests filter settings, defaults, access restrictions, etc.
*
* @todo This is for functions like filter_filter and check_markup, whose
* functionality is not completely focused on filtering. Some ideas:
@@ -1104,7 +1119,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
}
/**
- * Test the spam deterrent.
+ * Tests the spam deterrent no-follow filter.
*/
function testNoFollowFilter() {
// Setup dummy filter object.
@@ -1135,7 +1150,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase {
}
/**
- * Test the loose, admin HTML filter.
+ * Tests the permissive admin HTML filter.
*/
function testFilterXSSAdmin() {
// DRUPAL-SA-2008-044
@@ -1491,7 +1506,7 @@ www.example.com with a newline in comments -->
}
/**
- * Tests URL filter on longer content.
+ * Tests the URL filter on longer content.
*
* Filters based on regular expressions should also be tested with a more
* complex content than just isolated test lines.
@@ -1522,7 +1537,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.
*/
@@ -1713,7 +1728,7 @@ body {color:red}
}
/**
- * Asserts that a text transformed to lowercase with HTML entities decoded does contains a given string.
+ * Asserts that a lowercased, decoded HTML string contains another.
*
* Otherwise fails the test with a given message, similar to all the
* SimpleTest assert* functions.
@@ -1729,6 +1744,7 @@ body {color:red}
* Message to display if failed.
* @param $group
* The group this message belongs to, defaults to 'Other'.
+ *
* @return
* TRUE on pass, FALSE on fail.
*/
@@ -1737,7 +1753,7 @@ body {color:red}
}
/**
- * Asserts that text transformed to lowercase with HTML entities decoded does not contain a given string.
+ * Asserts that a lowercased, decoded HTML string does not contain another.
*
* Otherwise fails the test with a given message, similar to all the
* SimpleTest assert* functions.
@@ -1753,6 +1769,7 @@ body {color:red}
* Message to display if failed.
* @param $group
* The group this message belongs to, defaults to 'Other'.
+ *
* @return
* TRUE on pass, FALSE on fail.
*/
@@ -1780,7 +1797,7 @@ class FilterHooksTestCase extends DrupalWebTestCase {
}
/**
- * Test that hooks run correctly on creating, editing, and deleting a text format.
+ * Tests that hooks run correctly when adding, editing, or deleting a format.
*/
function testFilterHooks() {
// Add a text format.