diff --git a/modules/filter/filter.admin.inc b/modules/filter/filter.admin.inc
index 5a21e6e..60284d9 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.admin.js b/modules/filter/filter.admin.js
index 3bc6233..1233512 100644
--- a/modules/filter/filter.admin.js
+++ b/modules/filter/filter.admin.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Attaches administration-specific behavior for the Filter module.
+ */
+
(function ($) {
Drupal.behaviors.filterStatus = {
diff --git a/modules/filter/filter.install b/modules/filter/filter.install
index 9d17eb5..71ba97b 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.js b/modules/filter/filter.js
index c286159..e21d289 100644
--- a/modules/filter/filter.js
+++ b/modules/filter/filter.js
@@ -1,7 +1,12 @@
+/**
+ * @file
+ * Attaches behavior for the Filter module.
+ */
+
(function ($) {
/**
- * Automatically display the guidelines of the selected text format.
+ * Displays the guidelines of the selected text format automatically.
*/
Drupal.behaviors.filterGuidelines = {
attach: function (context) {
diff --git a/modules/filter/filter.module b/modules/filter/filter.module
index 7b451b7..182033f 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 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 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) {
@@ -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 dbbbe4c..50f8117 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 aa1693f..0c39495 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() {