diff --git a/core/modules/filter/filter.admin.inc b/core/modules/filter/filter.admin.inc index b4a7008..64d8e6d 100644 --- a/core/modules/filter/filter.admin.inc +++ b/core/modules/filter/filter.admin.inc @@ -1,15 +1,15 @@ $data) { if (is_array($data) && isset($data['weight'])) { @@ -95,7 +98,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 +114,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 +292,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 +311,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 +345,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 +363,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..181a0ad 100644 --- a/core/modules/filter/filter.api.php +++ b/core/modules/filter/filter.api.php @@ -1,5 +1,4 @@ FALSE while developing, but be sure to remove that @@ -56,8 +55,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 +69,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 +100,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 +276,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 +289,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 +306,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 3b8942f..3818873 100644 --- a/core/modules/filter/filter.module +++ b/core/modules/filter/filter.module @@ -1,8 +1,7 @@ name = trim($format->name); @@ -269,7 +275,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 +317,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 +356,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 +387,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 +435,7 @@ function filter_formats($account = NULL) { } /** - * Resets text format caches. + * Resets the text format caches. * * @see filter_formats() */ @@ -441,6 +451,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 +470,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 +505,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 +546,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 +571,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 +602,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 +619,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 +629,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 +658,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 +712,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 +734,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 +805,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,7 +954,7 @@ function filter_process_format($element) { } /** - * #pre_render callback for #type 'text_format' to hide field value from prying eyes. + * #pre_render callback: Hide 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 @@ -996,7 +1019,24 @@ 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 + * Boolean indicating whether the long form of tips should be returned. + * + * @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 +1070,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 +1092,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 +1164,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 +1173,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 +1195,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 +1288,7 @@ function _filter_html($text, $filter) { } /** - * Filter tips callback for HTML filter. + * Filters the tips callback for the HTML filter. */ function _filter_html_tips($filter, $format, $long = FALSE) { global $base_url; @@ -1345,7 +1386,7 @@ function _filter_html_tips($filter, $format, $long = FALSE) { } /** - * Settings callback for URL filter. + * Settings callback for the URL filter. */ function _filter_url_settings($form, &$form_state, $filter, $format, $defaults) { $filter->settings += $defaults; @@ -1525,7 +1566,7 @@ function _filter_url_parse_partial_links($match) { } /** - * preg_replace callback to escape contents of HTML comments + * preg_replace callback to escape contents of HTML comments. * * @param $match * An array containing matches to replace from preg_replace_callback(), @@ -1579,21 +1620,21 @@ function _filter_url_trim($text, $length = NULL) { } /** - * Filter tips callback for URL filter. + * Filters the tips callback for the URL filter. */ 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 +1700,7 @@ function _filter_autop($text) { } /** - * Filter tips callback for auto-paragraph filter. + * Filters the tips callback for the auto-paragraph filter. */ function _filter_autop_tips($filter, $format, $long = FALSE) { if ($long) { @@ -1678,7 +1719,7 @@ function _filter_html_escape($text) { } /** - * Filter tips callback for HTML escaping filter. + * Filters the tips callback for an HTML escaping filter. */ 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..73e9039 100644 --- a/core/modules/filter/filter.pages.inc +++ b/core/modules/filter/filter.pages.inc @@ -1,13 +1,13 @@ $format->name); @@ -111,7 +110,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. @@ -184,7 +183,9 @@ class FilterAdminTestCase extends DrupalWebTestCase { $this->web_user = $this->drupalCreateUser(array('create page content', 'edit own page content')); $this->drupalLogin($this->admin_user); } - + /** + * Tests the text format adminstration functionality. + */ function testFormatAdmin() { // Add text format. $this->drupalGet('admin/config/content/formats'); @@ -249,7 +250,7 @@ class FilterAdminTestCase extends DrupalWebTestCase { } /** - * Test filter administration functionality. + * Tests the filter administration functionality. */ function testFilterAdmin() { // URL filter. @@ -459,6 +460,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 +499,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 +523,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 +645,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 +662,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 +708,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 +725,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 +740,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 +758,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 +789,7 @@ class FilterSecurityTestCase extends DrupalWebTestCase { } /** - * Unit tests for core filters. + * Tests core filters. */ class FilterUnitTestCase extends DrupalUnitTestCase { public static function getInfo() { @@ -788,7 +801,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase { } /** - * Test the line break filter. + * Tests the line break filter. */ function testLineBreakFilter() { // Setup dummy filter object. @@ -1048,7 +1061,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase { } /** - * Test filter settings, defaults, access restrictions and similar. + * Tests filter settings, defaults, access restrictions, and similar things. * * @todo This is for functions like filter_filter and check_markup, whose * functionality is not completely focused on filtering. Some ideas: @@ -1104,7 +1117,7 @@ class FilterUnitTestCase extends DrupalUnitTestCase { } /** - * Test the spam deterrent. + * Tests the spam deterrent no-follow filter. */ function testNoFollowFilter() { // Setup dummy filter object. @@ -1135,7 +1148,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 +1504,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 +1535,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 +1726,10 @@ body {color:red} } /** - * Asserts that a text transformed to lowercase with HTML entities decoded does contains a given string. + * Asserts that a normalized string contains a given other string. + * + * Normalization here means transforming the string to lowercase and decoding + * HTML entities. * * Otherwise fails the test with a given message, similar to all the * SimpleTest assert* functions. @@ -1729,6 +1745,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 +1754,10 @@ body {color:red} } /** - * Asserts that text transformed to lowercase with HTML entities decoded does not contain a given string. + * Asserts that a normalized string does not contains a given other string. + * + * Normalization here means transforming the string to lowercase and decoding + * HTML entities. * * Otherwise fails the test with a given message, similar to all the * SimpleTest assert* functions. @@ -1753,6 +1773,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 +1801,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. @@ -1822,4 +1843,3 @@ class FilterHooksTestCase extends DrupalWebTestCase { $this->assertText('hook_filter_format_disable invoked.', t('hook_filter_format_disable() was invoked.')); } } -