diff --git a/core/modules/filter/filter.admin-rtl.css b/core/modules/filter/filter.admin-rtl.css
index 9fa9f42..c49481b 100644
--- a/core/modules/filter/filter.admin-rtl.css
+++ b/core/modules/filter/filter.admin-rtl.css
@@ -1,7 +1,7 @@
/**
* @file
- * RTL admin styling for the filter module.
+ * RTL admin styling for the Filter module.
*/
/**
diff --git a/core/modules/filter/filter.admin.css b/core/modules/filter/filter.admin.css
index d6004d5..fdb2eff 100644
--- a/core/modules/filter/filter.admin.css
+++ b/core/modules/filter/filter.admin.css
@@ -1,7 +1,7 @@
/**
* @file
- * Admin styling for the filter module.
+ * Admin styling for the Filter module.
*/
/**
diff --git a/core/modules/filter/filter.admin.inc b/core/modules/filter/filter.admin.inc
index 40a5eab..5a840aa 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,25 @@ 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: 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.
+ *
+ * @return
+ * A form array.
+ *
+ * @see filter_menu()
*/
function filter_admin_format_page($format = NULL) {
if (!isset($format->name)) {
@@ -109,11 +131,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 +322,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 +341,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 +375,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 +396,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 +405,3 @@ function filter_admin_disable_submit($form, &$form_state) {
$form_state['redirect'] = 'admin/config/content/formats';
}
-
diff --git a/core/modules/filter/filter.admin.js b/core/modules/filter/filter.admin.js
index b002041..b2d7c6e 100644
--- a/core/modules/filter/filter.admin.js
+++ b/core/modules/filter/filter.admin.js
@@ -1,3 +1,8 @@
+/**
+ * @file
+ * Attaches administration-specific behavior for the Filter module.
+ */
+
(function ($) {
"use strict";
diff --git a/core/modules/filter/filter.api.php b/core/modules/filter/filter.api.php
index 6675e4a..f11a528 100644
--- a/core/modules/filter/filter.api.php
+++ b/core/modules/filter/filter.api.php
@@ -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
diff --git a/core/modules/filter/filter.install b/core/modules/filter/filter.install
index da9ecb8..9237ad1 100644
--- a/core/modules/filter/filter.install
+++ b/core/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/core/modules/filter/filter.js b/core/modules/filter/filter.js
index 9482737..4bc8c18 100644
--- a/core/modules/filter/filter.js
+++ b/core/modules/filter/filter.js
@@ -1,9 +1,14 @@
+/**
+ * @file
+ * Attaches behavior for the Filter module.
+ */
+
(function ($) {
"use strict";
/**
- * 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/core/modules/filter/filter.module b/core/modules/filter/filter.module
index 4d9bfef..6c7007a 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.
*/
/**
@@ -78,6 +78,7 @@ function filter_theme() {
* Implements hook_element_info().
*
* @see filter_process_format()
+ * @see text_format_wrapper()
*/
function filter_element_info() {
$type['text_format'] = array(
@@ -139,13 +140,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.
@@ -153,7 +157,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.
@@ -171,29 +175,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);
@@ -278,7 +285,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
@@ -320,7 +327,9 @@ function filter_format_exists($format_id) {
}
/**
- * Display a text format form title.
+ * Displays a text format form title.
+ *
+ * @see filter_menu()
*/
function filter_admin_format_title($format) {
return $format->name;
@@ -357,6 +366,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).
@@ -387,11 +397,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.
@@ -434,7 +445,7 @@ function filter_formats($account = NULL) {
}
/**
- * Resets text format caches.
+ * Resets the text format caches.
*
* @see filter_formats()
*/
@@ -450,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.
*/
@@ -468,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.
@@ -502,6 +515,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.
*
@@ -542,6 +556,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()
*/
@@ -564,7 +581,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());
@@ -595,14 +612,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
@@ -610,6 +629,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,13 +639,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.
@@ -647,7 +668,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
@@ -701,18 +722,18 @@ 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
* filter_access() before accepting/using it. This is normally done in the
- * validation stage of the Form API. You should for example never make a preview
- * of content in a disallowed format.
+ * validation stage of the Form API. You should for example never make a
+ * preview of content in a disallowed format.
*
* @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
+ * The format ID of the text to be filtered. If no format is assigned, the
* fallback format will be used.
* @param $langcode
* Optional: the language code of the text to be filtered, e.g. 'en' for
@@ -723,6 +744,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) {
@@ -784,15 +808,16 @@ function check_markup($text, $format_id = NULL, $langcode = '', $cache = FALSE)
* Expands an element into a base element with text format selector attached.
*
* The form element will be expanded into two separate form elements, one
- * holding the original element, and the other holding the text format selector:
- * - value: Holds the original element, having its #type changed to the value of
- * #base_type or 'textarea' by default.
- * - format: Holds the text format fieldset and the text format selection, using
- * the text format id specified in #format or the user's default format by
- * default, if NULL.
+ * holding the original element, and the other holding the text format
+ * selector:
+ * - value: Holds the original element, having its #type changed to the value
+ * of #base_type or 'textarea' by default.
+ * - format: Holds the text format fieldset and the text format selection,
+ * using 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';
@@ -802,7 +827,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
@@ -940,11 +965,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.
*
@@ -1005,7 +1030,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;
@@ -1039,14 +1077,15 @@ 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 markup will be corrected on
+ * import.
+ *
* @return
* A DOMDocument that represents the loaded (X)HTML snippet.
*/
@@ -1061,15 +1100,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.
*/
@@ -1163,7 +1201,7 @@ function theme_filter_guidelines($variables) {
/**
* @defgroup standard_filters Standard filters
* @{
- * Filters implemented by the filter.module.
+ * Filters implemented by the Filter module.
*/
/**
@@ -1211,7 +1249,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;
@@ -1237,7 +1278,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);
@@ -1256,7 +1297,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;
@@ -1354,7 +1397,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;
@@ -1371,12 +1416,13 @@ 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.
* - E-mail addresses like name@example.com.
- * - Web addresses without the "http://" protocol defined, like www.example.com.
+ * - Web addresses without the "http://" protocol defined, like
+ * www.example.com.
* Each type must be processed separately, as there is no one regular
* expression that could possibly match all of the cases in one pass.
*/
@@ -1494,7 +1540,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.
@@ -1507,7 +1555,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.
@@ -1520,7 +1570,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.
@@ -1533,7 +1585,9 @@ 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(),
@@ -1587,21 +1641,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) {
@@ -1667,7 +1724,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) {
@@ -1686,7 +1745,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/core/modules/filter/filter.pages.inc b/core/modules/filter/filter.pages.inc
index ce8fdb9..8660427 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,13 +21,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/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php
index d6bcb65..21540da 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php
@@ -100,7 +100,7 @@ class FilterAdminTest extends WebTestBase {
}
/**
- * Test filter administration functionality.
+ * Tests filter administration functionality.
*/
function testFilterAdmin() {
// URL filter.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php
index 54369a5..8cea497 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php
@@ -31,7 +31,7 @@ class FilterCrudTest extends WebTestBase {
}
/**
- * 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.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php
index d4733bc..e3e2645 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php
@@ -18,6 +18,9 @@ class FilterDefaultFormatTest extends WebTestBase {
);
}
+ /**
+ * 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.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php
index d6a08c6..bc284c9 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php
@@ -105,6 +105,9 @@ class FilterFormatAccessTest extends WebTestBase {
$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.
$roles = $this->web_user->roles;
@@ -128,7 +131,7 @@ class FilterFormatAccessTest extends WebTestBase {
}
/**
- * 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
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php
index 841c502..a6522c2 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php
@@ -36,7 +36,7 @@ class FilterHooksTest extends WebTestBase {
}
/**
- * Test that hooks run correctly on creating, editing, and deleting a text format.
+ * Tests that hooks run correctly on creating, editing, and deleting a text format.
*/
function testFilterHooks() {
// Add a text format.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterNoFormatTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterNoFormatTest.php
index fa87f7c..01c3f75 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterNoFormatTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterNoFormatTest.php
@@ -9,6 +9,9 @@ namespace Drupal\filter\Tests;
use Drupal\simpletest\WebTestBase;
+/**
+ * Tests the behavior of check_markup() when it is called without text format.
+ */
class FilterNoFormatTest extends WebTestBase {
public static function getInfo() {
return array(
@@ -18,6 +21,10 @@ class FilterNoFormatTest extends WebTestBase {
);
}
+ /**
+ * Tests if text with no format is filtered the same 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.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php
index 27e0e00..3c35629 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php
@@ -51,7 +51,7 @@ class FilterSecurityTest extends WebTestBase {
}
/**
- * Test that filtered content is emptied when an actively used filter module is disabled.
+ * Tests that filtered content is emptied when an actively used filter module is disabled.
*/
function testDisableFilterModule() {
// Create a new node.
diff --git a/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php b/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
index 9daac0f..7dab9f6 100644
--- a/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
+++ b/core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php
@@ -23,7 +23,7 @@ class FilterUnitTest extends UnitTestBase {
}
/**
- * Test the line break filter.
+ * Tests the line break filter.
*/
function testLineBreakFilter() {
// Setup dummy filter object.
@@ -283,7 +283,7 @@ class FilterUnitTest extends UnitTestBase {
}
/**
- * 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:
@@ -339,7 +339,7 @@ class FilterUnitTest extends UnitTestBase {
}
/**
- * Test the spam deterrent.
+ * Tests the spam deterrent.
*/
function testNoFollowFilter() {
// Setup dummy filter object.
@@ -370,7 +370,7 @@ class FilterUnitTest extends UnitTestBase {
}
/**
- * Test the loose, admin HTML filter.
+ * Tests the loose, admin HTML filter.
*/
function testFilterXSSAdmin() {
// DRUPAL-SA-2008-044
@@ -764,7 +764,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.
*/