Issue #2002182 by w00zle: Convert hook_filter_info docs to use new callback function standard

4 files changed, 55 insertions, 34 deletions

diff --git a/modules/filter/filter.api.php b/modules/filter/filter.api.php
index 6675e4af5..2901eb95b 100644
--- a/modules/filter/filter.api.php
+++ b/modules/filter/filter.api.php
@@ -57,20 +57,20 @@
  *   - 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.
+ *     elements for the filter. See callback_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
- *     the actual filtering happens. See hook_filter_FILTER_prepare() for
+ *     the actual filtering happens. See callback_filter_prepare() for
  *     details.
  *   - process callback: (required) The name the function that performs the
- *     actual filtering. See hook_filter_FILTER_process() for details.
+ *     actual filtering. See callback_filter_process() for details.
  *   - cache (default TRUE): Specifies whether the filtered text can be cached.
  *     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
+ *     usage guidelines for the filter. See callback_filter_tips() for
  *     details.
  *   - weight: A default weight for the filter in new text formats.
  *
@@ -122,11 +122,9 @@ function hook_filter_info_alter(&$info) {
  */
 
 /**
- * Settings callback for hook_filter_info().
+ * Provide a settings form for filter settings.
  *
- * Note: This is not really a hook. The function name is manually specified via
- * 'settings callback' in hook_filter_info(), with this recommended callback
- * name pattern. It is called from filter_admin_format_form().
+ * Callback for hook_filter_info().
  *
  * This callback function is used to provide a settings form for filter
  * settings, for filters that need settings on a per-text-format basis. This
@@ -158,8 +156,10 @@ function hook_filter_info_alter(&$info) {
  * @return
  *   An array of form elements defining settings for the filter. Array keys
  *   should match the array keys in $filter->settings and $defaults.
+ *
+ * @ingroup callbacks
  */
-function hook_filter_FILTER_settings($form, &$form_state, $filter, $format, $defaults, $filters) {
+function callback_filter_settings($form, &$form_state, $filter, $format, $defaults, $filters) {
   $filter->settings += $defaults;
 
   $elements = array();
@@ -172,11 +172,9 @@ function hook_filter_FILTER_settings($form, &$form_state, $filter, $format, $def
 }
 
 /**
- * Prepare callback for hook_filter_info().
+ * Provide prepared text with special characters escaped.
  *
- * Note: This is not really a hook. The function name is manually specified via
- * 'prepare callback' in hook_filter_info(), with this recommended callback
- * name pattern. It is called from check_markup().
+ * Callback for hook_filter_info().
  *
  * See hook_filter_info() for a description of the filtering process. Filters
  * should not use the 'prepare callback' step for anything other than escaping,
@@ -199,19 +197,19 @@ function hook_filter_FILTER_settings($form, &$form_state, $filter, $format, $def
  *
  * @return
  *   The prepared, escaped text.
+ *
+ * @ingroup callbacks
  */
-function hook_filter_FILTER_prepare($text, $filter, $format, $langcode, $cache, $cache_id) {
+function callback_filter_prepare($text, $filter, $format, $langcode, $cache, $cache_id) {
   // Escape <code> and </code> tags.
   $text = preg_replace('|<code>(.+?)</code>|se', "[codefilter_code]$1[/codefilter_code]", $text);
   return $text;
 }
 
 /**
- * Process callback for hook_filter_info().
+ * Provide text filtered to conform to the supplied format.
  *
- * Note: This is not really a hook. The function name is manually specified via
- * 'process callback' in hook_filter_info(), with this recommended callback
- * name pattern. It is called from check_markup().
+ * Callback for hook_filter_info().
  *
  * See hook_filter_info() for a description of the filtering process. This step
  * is where the filter actually transforms the text.
@@ -232,19 +230,19 @@ function hook_filter_FILTER_prepare($text, $filter, $format, $langcode, $cache,
  *
  * @return
  *   The filtered text.
+ *
+ * @ingroup callbacks
  */
-function hook_filter_FILTER_process($text, $filter, $format, $langcode, $cache, $cache_id) {
+function callback_filter_process($text, $filter, $format, $langcode, $cache, $cache_id) {
   $text = preg_replace('|\[codefilter_code\](.+?)\[/codefilter_code\]|se', "<pre>$1</pre>", $text);
 
   return $text;
 }
 
 /**
- * Tips callback for hook_filter_info().
+ * Return help text for a filter.
  *
- * Note: This is not really a hook. The function name is manually specified via
- * 'tips callback' in hook_filter_info(), with this recommended callback
- * name pattern. It is called from _filter_tips().
+ * Callback for hook_filter_info().
  *
  * A filter's tips should be informative and to the point. Short tips are
  * preferably one-liners.
@@ -260,8 +258,10 @@ function hook_filter_FILTER_process($text, $filter, $format, $langcode, $cache,
  *
  * @return
  *   Translated text to display as a tip.
+ *
+ * @ingroup callbacks
  */
-function hook_filter_FILTER_tips($filter, $format, $long) {
+function callback_filter_tips($filter, $format, $long) {
  if ($long) {
     return t('Lines and paragraphs are automatically recognized. The &lt;br /&gt; line break, &lt;p&gt; paragraph and &lt;/p&gt; close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.');
   }
diff --git a/modules/filter/filter.module b/modules/filter/filter.module
index 182033fe8..67b2c2f7f 100644
--- a/modules/filter/filter.module
+++ b/modules/filter/filter.module
@@ -1256,10 +1256,9 @@ function filter_filter_info() {
 }
 
 /**
- * Filter settings callback for the HTML content filter.
+ * Implements callback_filter_settings().
  *
- * See hook_filter_FILTER_settings() for documentation of parameters and return
- * value.
+ * Filter settings callback for the HTML content filter.
  */
 function _filter_html_settings($form, &$form_state, $filter, $format, $defaults) {
   $filter->settings += $defaults;
@@ -1285,6 +1284,8 @@ function _filter_html_settings($form, &$form_state, $filter, $format, $defaults)
 }
 
 /**
+ * Implements callback_filter_process().
+ *
  * Provides filtering of input into accepted HTML.
  */
 function _filter_html($text, $filter) {
@@ -1304,7 +1305,9 @@ function _filter_html($text, $filter) {
 }
 
 /**
- * Filter tips callback: Provides help for the HTML filter.
+ * Implements callback_filter_tips().
+ *
+ * Provides help for the HTML filter.
  *
  * @see filter_filter_info()
  */
@@ -1404,7 +1407,9 @@ function _filter_html_tips($filter, $format, $long = FALSE) {
 }
 
 /**
- * Filter URL settings callback: Provides settings for the URL filter.
+ * Implements callback_filter_settings().
+ *
+ * Provides settings for the URL filter.
  *
  * @see filter_filter_info()
  */
@@ -1425,6 +1430,8 @@ function _filter_url_settings($form, &$form_state, $filter, $format, $defaults)
 }
 
 /**
+ * Implements callback_filter_process().
+ *
  * Converts text into hyperlinks automatically.
  *
  * This filter identifies and makes clickable three types of "links".
@@ -1650,7 +1657,9 @@ function _filter_url_trim($text, $length = NULL) {
 }
 
 /**
- * Filter tips callback: Provides help for the URL filter.
+ * Implements callback_filter_tips().
+ *
+ * Provides help for the URL filter.
  *
  * @see filter_filter_info()
  */
@@ -1659,6 +1668,8 @@ function _filter_url_tips($filter, $format, $long = FALSE) {
 }
 
 /**
+ * Implements callback_filter_process().
+ *
  * Scans the input and makes sure that HTML tags are properly closed.
  */
 function _filter_htmlcorrector($text) {
@@ -1666,6 +1677,8 @@ function _filter_htmlcorrector($text) {
 }
 
 /**
+ * Implements callback_filter_process().
+ *
  * Converts line breaks into <p> and <br> in an intelligent fashion.
  *
  * Based on: http://photomatt.net/scripts/autop
@@ -1733,7 +1746,9 @@ function _filter_autop($text) {
 }
 
 /**
- * Filter tips callback: Provides help for the auto-paragraph filter.
+ * Implements callback_filter_tips().
+ *
+ * Provides help for the auto-paragraph filter.
  *
  * @see filter_filter_info()
  */
@@ -1747,6 +1762,8 @@ function _filter_autop_tips($filter, $format, $long = FALSE) {
 }
 
 /**
+ * Implements callback_filter_process().
+ *
  * Escapes all HTML tags, so they will be visible instead of being effective.
  */
 function _filter_html_escape($text) {
@@ -1754,7 +1771,9 @@ function _filter_html_escape($text) {
 }
 
 /**
- * Filter tips callback: Provides help for the HTML escaping filter.
+ * Implements callback_filter_tips().
+ *
+ * Provides help for the HTML escaping filter.
  *
  * @see filter_filter_info()
  */
diff --git a/modules/php/php.module b/modules/php/php.module
index d5ea15287..da9d01db4 100644
--- a/modules/php/php.module
+++ b/modules/php/php.module
@@ -47,7 +47,7 @@ function php_permission() {
  * overwrite any variables in the calling code, unlike a regular eval() call.
  *
  * This function is also used as an implementation of
- * hook_filter_FILTER_process().
+ * callback_filter_process().
  *
  * @param $code
  *   The code to evaluate.
@@ -88,7 +88,7 @@ function php_eval($code) {
 }
 
 /**
- * Implements hook_filter_FILTER_tips().
+ * Implements callback_filter_tips().
  *
  * @see php_filter_info()
  */
diff --git a/modules/simpletest/tests/filter_test.module b/modules/simpletest/tests/filter_test.module
index 2cebc7085..63b7f66d6 100644
--- a/modules/simpletest/tests/filter_test.module
+++ b/modules/simpletest/tests/filter_test.module
@@ -44,6 +44,8 @@ function filter_test_filter_info() {
 }
 
 /**
+ * Implements callback_filter_process().
+ *
  * Process handler for filter_test_replace filter.
  *
  * Replaces all text with filter and text format information.