Issue #1347914 by batigolix, NROTC_Webmaster, sven.lauer: Clean up API docs for filter module

core/modules/filter/filter.admin-rtl.css

 
 /**
  * @file
- * RTL admin styling for the filter module.
+ * RTL admin styling for the Filter module.
  */
 
 /**

core/modules/filter/filter.admin.css

 
 /**
  * @file
- * Admin styling for the filter module.
+ * Admin styling for the Filter module.
  */
 
 /**

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';
 }
-

core/modules/filter/filter.admin.js

+/**
+ * @file
+ * Attaches administration-specific behavior for the Filter module.
+ */
+
 (function ($) {
 
 "use strict";

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

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.
  */
 
 /**

core/modules/filter/filter.js

+/**
+ * @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) {

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 = NULL) {
   if (!empty($format)) {
@@ -19,13 +20,12 @@ function filter_tips_long($format = NULL) {
   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

core/modules/filter/lib/Drupal/filter/Tests/FilterAdminTest.php

@@ -100,7 +100,7 @@ function testFormatAdmin() {
   }
 
   /**
-   * Test filter administration functionality.
+   * Tests filter administration functionality.
    */
   function testFilterAdmin() {
     // URL filter.

core/modules/filter/lib/Drupal/filter/Tests/FilterCrudTest.php

@@ -31,7 +31,7 @@ public static function getInfo() {
   }
 
   /**
-   * 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.

core/modules/filter/lib/Drupal/filter/Tests/FilterDefaultFormatTest.php

@@ -18,6 +18,9 @@ public static function getInfo() {
     );
   }
 
+  /**
+   * 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.

core/modules/filter/lib/Drupal/filter/Tests/FilterFormatAccessTest.php

@@ -126,6 +126,9 @@ function testFormatPermissions() {
     $this->assertResponse(404);
   }
 
+  /**
+   * 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;
@@ -149,7 +152,7 @@ function testFormatRoles() {
   }
 
   /**
-   * 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

core/modules/filter/lib/Drupal/filter/Tests/FilterHooksTest.php

@@ -36,7 +36,7 @@ function setUp() {
   }
 
   /**
-   * 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.

core/modules/filter/lib/Drupal/filter/Tests/FilterNoFormatTest.php

@@ -9,6 +9,9 @@
 
 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 @@ public static function getInfo() {
     );
   }
 
+  /**
+   * 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.

core/modules/filter/lib/Drupal/filter/Tests/FilterSecurityTest.php

@@ -51,7 +51,7 @@ function setUp() {
   }
 
   /**
-   * 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.

core/modules/filter/lib/Drupal/filter/Tests/FilterUnitTest.php

@@ -23,7 +23,7 @@ public static function getInfo() {
   }
 
   /**
-   * Test the line break filter.
+   * Tests the line break filter.
    */
   function testLineBreakFilter() {
     // Setup dummy filter object.
@@ -283,7 +283,7 @@ function testFilterXSS() {
   }
 
   /**
-   * 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 @@ function testHtmlFilter() {
   }
 
   /**
-   * Test the spam deterrent.
+   * Tests the spam deterrent.
    */
   function testNoFollowFilter() {
     // Setup dummy filter object.
@@ -370,7 +370,7 @@ function testNoFollowFilter() {
   }
 
   /**
-   * Test the loose, admin HTML filter.
+   * Tests the loose, admin HTML filter.
    */
   function testFilterXSSAdmin() {
     // DRUPAL-SA-2008-044
@@ -764,7 +764,7 @@ function testUrlFilterContent() {
   }
 
   /**
-   * Test the HTML corrector filter.
+   * Tests the HTML corrector filter.
    *
    * @todo This test could really use some validity checking function.
    */