- Patch #704866 by jhodgdon: search API doc has some problems.

modules/search/search.api.php

@@ -12,25 +12,22 @@
  */
 
 /**
- * Define a custom search routine.
+ * Define a custom search type.
  *
- * This hook allows a module to perform searches on content it defines
- * (custom node types, users, or comments, for example) when a site search
- * is performed.
+ * This hook allows a module to tell search.module that it wishes to perform
+ * searches on content it defines (custom node types, users, or comments for
+ * example) when a site search is performed.
  *
- * Note that you can use form API to extend the search. You will need to use
- * hook_form_alter() to add any additional required form elements. You can
- * process their values on submission using a custom validation function.
- * You will need to merge any custom search values into the search keys
- * using a key:value syntax. This allows all search queries to have a clean
- * and permanent URL. See node_form_search_form_alter() for an example.
- *
- * You can also alter the display of your module's search results
- * by implementing hook_search_page().
- *
- * The example given here is for node.module, which uses the indexed search
- * capabilities. To do this, node module also implements hook_update_index()
- * which is used to create and maintain the index.
+ * In order for the search to do anything, your module must also implement
+ * hook_search_execute(), which is called when someone requests a search
+ * on your module's type of content. If you want to have your content
+ * indexed in the standard search index, your module should also implement
+ * hook_update_index(). If your search type has settings, you can implement
+ * hook_search_admin() to add them to the search settings page. You can also
+ * alter the display of your module's search results by implementing
+ * hook_search_page(). And you can use hook_form_FORM_ID_alter(), with
+ * FORM_ID set to 'search', to add fields to the search form. See
+ * node_form_search_form_alter() for an example.
  *
  * @return
  *   Array with the optional keys 'title' for the tab title and 'path' for
@@ -49,7 +46,7 @@ function hook_search_info() {
 /**
  * Define access to a custom search routine.
  *
- * This hook allows a module to deny access to a user to a search tab.
+ * This hook allows a module to define permissions for a search tab.
  *
  * @ingroup search
  */
@@ -58,9 +55,9 @@ function hook_search_access() {
 }
 
 /**
- * The search index is going to be rebuilt.
+ * Take action when the search index is going to be rebuilt.
  *
- * Modules which use  hook_update_index() should update their indexing
+ * Modules that use hook_update_index() should update their indexing
  * bookkeeping so that it starts from scratch the next time
  * hook_update_index() is called.
  *
@@ -90,10 +87,10 @@ function hook_search_status() {
 }
 
 /**
- * Add elements to the search administration form.
+ * Add elements to the search settings form.
  *
  * @return
- *   The form array for the Search settings page at admin/config/search/settings.
+ *   Form array for the Search settings page at admin/config/search/settings.
  *
  * @ingroup search
  */
@@ -124,8 +121,21 @@ function hook_search_admin() {
 /**
  * Execute a search for a set of key words.
  *
- * We call do_search() with the keys, the module name, and extra SQL fragments
- * to use when searching. See hook_update_index() for more information.
+ * Use database API with the 'PagerDefault' query extension to perform your
+ * search.
+ *
+ * If your module uses hook_update_index() and search_index() to index its
+ * items, use table 'search_index' aliased to 'i' as the main table in your
+ * query, with the 'SearchQuery' extension. You can join to your module's table
+ * using the 'i.sid' field, which will contain the $sid values you provided to
+ * search_index(). Add the main keywords to the query by using method
+ * searchExpression(). The functions search_expression_extract() and
+ * search_expression_insert() may also be helpful for adding custom search
+ * parameters to the search expression.
+ *
+ * See node_execute_search() for an example of a module that uses the search
+ * index, and user_execute_search() for an example that doesn't ues the search
+ * index.
  *
  * @param $keys
  *   The search keywords as entered by the user.
@@ -146,7 +156,7 @@ function hook_search_admin() {
  */
 function hook_search_execute($keys = NULL) {
   // Build matching conditions
-  $query = db_search()->extend('PagerDefault');
+  $query = db_select('search_index', 'i', array('target' => 'slave'))->extend('SearchQuery')->extend('PagerDefault');
   $query->join('node', 'n', 'n.nid = i.sid');
   $query
     ->condition('n.status', 1)
@@ -211,18 +221,17 @@ function hook_search_execute($keys = NULL) {
  *
  * A module that implements hook_search() 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').
+ * 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 a definition
- * list. So your hook_search_page() implementation should probably do
- * this as well.
+ * Note that by default, theme('search_results') and theme('search_result')
+ * work together to create a definition list (DL). 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
  *   An HTML string containing the formatted search results, with
  *   a pager included.
@@ -240,21 +249,26 @@ function hook_search_page($results) {
 }
 
 /**
- * Preprocess text for the search index.
+ * Preprocess text for search.
  *
- * This hook is called both for text added to the search index, as well as
+ * This hook is called to preprocess both the text added to the search index and
  * the keywords users have submitted for searching.
  *
- * This is required for example to allow Japanese or Chinese text to be
- * searched. As these languages do not use spaces, it needs to be split into
- * separate words before it can be indexed. There are various external
- * libraries for this.
+ * Possible uses:
+ * - Adding spaces between words of Chinese or Japanese text.
+ * - Stemming words down to their root words to allow matches between, for
+ *   instance, walk, walked, walking, and walks in searching.
+ * - Expanding abbreviations and acronymns that occur in text.
  *
  * @param $text
- *   The text to split. This is a single piece of plain-text that was
- *   extracted from between two HTML tags. Will not contain any HTML entities.
+ *   The text to preprocess. This is a single piece of plain text extracted
+ *   from between two HTML tags or from the search query. It will not contain
+ *   any HTML entities or HTML tags.
+ *
  * @return
- *   The text after processing.
+ *   The text after preprocessing. Note that if your module decides not to alter
+ *   the text, it should return the original text. Also, after preprocessing,
+ *   words in the text should be separated by a space.
  *
  * @ingroup search
  */
@@ -264,26 +278,22 @@ function hook_search_preprocess($text) {
 }
 
 /**
- * Update Drupal's full-text index for this module.
- *
- * Modules can implement this hook if they want to use the full-text indexing
- * mechanism in Drupal.
- *
- * This hook is called every cron run if search.module is enabled. A module
- * should check which of its items were modified or added since the last
- * run. It is advised that you implement a throttling mechanism which indexes
- * at most 'search_cron_limit' items per run (see example below).
+ * Update the search index for this module.
  *
- * You should also be aware that indexing may take too long and be aborted if
- * there is a PHP time limit. That's why you should update your internal
- * bookkeeping multiple times per run, preferably after every item that
- * is indexed.
+ * This hook is called every cron run if search.module is enabled, your
+ * module has implemented hook_search_info(), and your module has been set as
+ * an active search module on the Search settings page
+ * (admin/config/search/settings). It allows your module to add items to the
+ * built-in search index using search_index(), or to add them to your module's
+ * own indexing mechanism.
  *
- * Per item that needs to be indexed, you should call search_index() with
- * its content as a single HTML string. The search indexer will analyse the
- * HTML and use it to assign higher weights to important words (such as
- * titles). It will also check for links that point to nodes, and use them to
- * boost the ranking of the target nodes.
+ * When implementing this hook, your module should index content items that
+ * were modified or added since the last run. PHP has a time limit
+ * for cron, though, so it is advisable to limit how many items you index
+ * per run using variable_get('search_cron_limit') (see example below). Also,
+ * since the cron run could time out and abort in the middle of your run, you
+ * should update your module's internal bookkeeping on when items have last
+ * been indexed as you go rather than waiting to the end of indexing.
  *
  * @ingroup search
  */