Issue #1948564 by bdgreen, aitiba, joachim: Document hook_search_info() callback using new callback definition standard

1 files changed, 27 insertions, 18 deletions

diff --git a/modules/search/search.api.php b/modules/search/search.api.php
index 534c1e872..797f7e4e8 100644
--- a/modules/search/search.api.php
+++ b/modules/search/search.api.php
@@ -30,15 +30,11 @@
  *
  * @return
  *   Array with optional keys:
- *   - 'title': Title for the tab on the search page for this module. Defaults
+ *   - title: Title for the tab on the search page for this module. Defaults
  *     to the module name if not given.
- *   - 'path': Path component after 'search/' for searching with this module.
+ *   - path: Path component after 'search/' for searching with this module.
  *     Defaults to the module name if not given.
- *   - 'conditions_callback': Name of a callback function that is invoked by
- *     search_view() to get an array of additional search conditions to pass to
- *     search_data(). For example, a search module may get additional keywords,
- *     filters, or modifiers for the search from the query string. Sample
- *     callback function: sample_search_conditions_callback().
+ *   - conditions_callback: An implementation of callback_search_conditions().
  *
  * @ingroup search
  */
@@ -46,21 +42,33 @@ function hook_search_info() {
   return array(
     'title' => 'Content',
     'path' => 'node',
-    'conditions_callback' => 'sample_search_conditions_callback',
+    'conditions_callback' => 'callback_search_conditions',
   );
 }
 
 /**
- * An example conditions callback function for search.
+ * Provide search query conditions.
+ *
+ * Callback for hook_search_info().
+ *
+ * This callback is invoked by search_view() to get an array of additional
+ * search conditions to pass to search_data(). For example, a search module
+ * may get additional keywords, filters, or modifiers for the search from
+ * the query string.
  *
  * This example pulls additional search keywords out of the $_REQUEST variable,
  * (i.e. from the query string of the request). The conditions may also be
  * generated internally - for example based on a module's settings.
  *
- * @see hook_search_info()
+ * @param $keys
+ *   The search keywords string.
+ *
+ * @return
+ *   An array of additional conditions, such as filters.
+ *
  * @ingroup search
  */
-function sample_search_conditions_callback($keys) {
+function callback_search_conditions($keys) {
   $conditions = array();
 
   if (!empty($_REQUEST['keys'])) {
@@ -252,22 +260,23 @@ function hook_search_execute($keys = NULL, $conditions = NULL) {
 /**
  * Override the rendering of search results.
  *
- * A module that implements hook_search_info() to define a type of search
- * may implement this hook in order to override the default theming of
- * its search results, which is otherwise themed using theme('search_results').
+ * A module that implements hook_search_info() to define a type of search may
+ * implement this hook in order to override the default theming of its search
+ * results, which is otherwise themed using theme('search_results').
  *
  * Note that by default, theme('search_results') and theme('search_result')
  * work together to create an ordered list (OL). So your hook_search_page()
  * implementation should probably do this as well.
  *
- * @see search-result.tpl.php, search-results.tpl.php
- *
  * @param $results
  *   An array of search results.
  *
  * @return
- *   A renderable array, which will render the formatted search results with
- *   a pager included.
+ *   A renderable array, which will render the formatted search results with a
+ *   pager included.
+ *
+ * @see search-result.tpl.php
+ * @see search-results.tpl.php
  */
 function hook_search_page($results) {
   $output['prefix']['#markup'] = '<ol class="search-results">';