- Patch #827116 by jhodgdon, marvil07: search API is inconsistent in /, and generally needs doc cleanup.

6 files changed, 92 insertions, 82 deletions

diff --git a/modules/search/search-result.tpl.php b/modules/search/search-result.tpl.php
index 625133fb7..667540adb 100644
--- a/modules/search/search-result.tpl.php
+++ b/modules/search/search-result.tpl.php
@@ -20,7 +20,7 @@
  *   as "node" or "user".
  *
  * Default keys within $info_split:
- * - $info_split['type']: Node type.
+ * - $info_split['type']: Node type (or item type string supplied by module).
  * - $info_split['user']: Author of the node linked to users profile. Depends
  *   on permission.
  * - $info_split['date']: Last update of the node. Short formatted.
diff --git a/modules/search/search.api.php b/modules/search/search.api.php
index f6209987f..13b812aab 100644
--- a/modules/search/search.api.php
+++ b/modules/search/search.api.php
@@ -181,7 +181,7 @@ function hook_search_admin() {
  *   An array of search results. To use the default search result
  *   display, each item should have the following keys':
  *   - 'link': Required. The URL of the found item.
- *   - 'type': The type of item.
+ *   - 'type': The type of item (such as the content type).
  *   - 'title': Required. The name of the item.
  *   - 'user': The author of the item.
  *   - 'date': A timestamp when the item was last modified.
@@ -272,8 +272,8 @@ function hook_search_page($results) {
 
   foreach ($results as $entry) {
     $output[] = array(
-      '#theme' => 'search_result', 
-      '#result' => $entry, 
+      '#theme' => 'search_result',
+      '#result' => $entry,
       '#module' => 'my_module_name',
     );
   }
diff --git a/modules/search/search.extender.inc b/modules/search/search.extender.inc
index 6c0c7600b..5347bb52a 100644
--- a/modules/search/search.extender.inc
+++ b/modules/search/search.extender.inc
@@ -22,8 +22,8 @@
  * The second portion of the query further refines this set by verifying
  * advanced text conditions (such as negative or phrase matches).
  *
- * The used query object has the tag 'search_$type' and can be further extended
- * with hook_query_alter().
+ * The used query object has the tag 'search_$module' and can be further
+ * extended with hook_query_alter().
  */
 class SearchQuery extends SelectQueryExtender {
   /**
@@ -34,9 +34,11 @@ class SearchQuery extends SelectQueryExtender {
   protected $searchExpression;
 
   /**
-   * Type of search.
+   * Type of search (search module).
    *
-   * This maps to the value of the type column in search_index.
+   * This maps to the value of the type column in search_index, and is equal
+   * to the machine-readable name of the module that implements
+   * hook_search_info().
    *
    * @var string
    */
@@ -50,7 +52,7 @@ class SearchQuery extends SelectQueryExtender {
   protected $keys = array('positive' => array(), 'negative' => array());
 
   /**
-   * Indicates if the first pass query requires complex conditions (LIKE).
+   * Indicates whether the first pass query requires complex conditions (LIKE).
    *
    * @var boolean.
    */
@@ -94,7 +96,7 @@ class SearchQuery extends SelectQueryExtender {
   protected $normalize;
 
   /**
-   * Indicates if the first pass query has been executed.
+   * Indicates whether the first pass query has been executed.
    *
    * @var boolean
    */
@@ -122,33 +124,35 @@ class SearchQuery extends SelectQueryExtender {
   protected $multiply = array();
 
   /**
-   * Search items for the given search query string and type.
+   * Sets up the search query expression.
    *
    * @param $query
-   *   A search query string, that can contain options.
-   * @param $type
-   *   The type of search, this maps to {search_index}.type.
+   *   A search query string, which can contain options.
+   * @param $module
+   *   The search module. This maps to {search_index}.type in the database.
+   *
    * @return
    *   The SearchQuery object.
    */
-  public function searchExpression($expression, $type) {
+  public function searchExpression($expression, $module) {
     $this->searchExpression = $expression;
-    $this->type = $type;
+    $this->type = $module;
 
     return $this;
   }
 
   /**
-   * Apply a search option and remove it from the search query string.
+   * Applies a search option and removes it from the search query string.
    *
    * These options are in the form option:value,value2,value3.
    *
    * @param $option
    *   Name of the option.
    * @param $column
-   *   Name of the db column to which the value should be applied.
+   *   Name of the database column to which the value should be applied.
+   *
    * @return
-   *   TRUE if at least a value for that option has been found, FALSE if not.
+   *   TRUE if a value for that option was found, FALSE if not.
    */
   public function setOption($option, $column) {
     if ($values = search_expression_extract($this->searchExpression, $option)) {
@@ -164,9 +168,9 @@ class SearchQuery extends SelectQueryExtender {
   }
 
   /**
-   * Parse a search query into SQL conditions.
+   * Parses the search query into SQL conditions.
    *
-   * We build two queries that matches the dataset bodies.
+   * We build two queries that match the dataset bodies.
    */
   protected function parseSearchExpression() {
     // Matchs words optionally prefixed by a dash. A word in this case is
@@ -303,10 +307,10 @@ class SearchQuery extends SelectQueryExtender {
   }
 
   /**
-   * Execute the first pass query.
+   * Executes the first pass query.
    *
    * This can either be done explicitly, so that additional scores and
-   * conditions can be applied to the second pass query or implicitly by
+   * conditions can be applied to the second pass query, or implicitly by
    * addScore() or execute().
    *
    * @return
@@ -362,7 +366,7 @@ class SearchQuery extends SelectQueryExtender {
   /**
    * Adds a custom score expression to the search query.
    *
-   * Each score expression can optionally use a multiplicator and multiple
+   * Each score expression can optionally use a multiplier, and multiple
    * expressions are combined.
    *
    * @param $score
@@ -388,15 +392,15 @@ class SearchQuery extends SelectQueryExtender {
   }
 
   /**
-   * Execute the search.
+   * Executes the search.
    *
-   * If not already done, this executes the first pass query, then the complex
+   * If not already done, this executes the first pass query. Then the complex
    * conditions are applied to the query including score expressions and
    * ordering.
    *
    * @return
-   *   FALSE if the first pass query returned no results and a database result
-   *   set if not.
+   *   FALSE if the first pass query returned no results, and a database result
+   *   set if there were results.
    */
   public function execute()
   {
@@ -447,10 +451,10 @@ class SearchQuery extends SelectQueryExtender {
   }
 
   /**
-   * Build the default count query for SearchQuery.
+   * Builds the default count query for SearchQuery.
    *
-   * Since SearchQuery always uses GROUP BY, we can default to a subquery. Also
-   * adding the same conditions as execute() because countQuery() is called
+   * Since SearchQuery always uses GROUP BY, we can default to a subquery. We
+   * also add the same conditions as execute() because countQuery() is called
    * first.
    */
   public function countQuery() {
diff --git a/modules/search/search.module b/modules/search/search.module
index 82eb65d37..3489fd74f 100644
--- a/modules/search/search.module
+++ b/modules/search/search.module
@@ -297,41 +297,44 @@ function _search_menu_access($name) {
 }
 
 /**
- * Wipes a part of or the entire search index.
+ * Clears a part of or the entire search index.
  *
  * @param $sid
- *  (optional) The SID of the item to wipe. If specified, $type must be passed
- *  too.
- * @param $type
- *  (optional) The type of item to wipe.
+ *   (optional) The ID of the item to remove from the search index. If
+ *   specified, $module must also be given. Omit both $sid and $module to clear
+ *   the entire search index.
+ * @param $module
+ *   (optional) The machine-readable name of the module for the item to remove
+ *   from the search index.
  */
-function search_reindex($sid = NULL, $type = NULL, $reindex = FALSE) {
-  if ($type == NULL && $sid == NULL) {
+function search_reindex($sid = NULL, $module = NULL, $reindex = FALSE) {
+  if ($module == NULL && $sid == NULL) {
     module_invoke_all('search_reset');
   }
   else {
     db_delete('search_dataset')
       ->condition('sid', $sid)
-      ->condition('type', $type)
+      ->condition('type', $module)
       ->execute();
     db_delete('search_index')
       ->condition('sid', $sid)
-      ->condition('type', $type)
+      ->condition('type', $module)
       ->execute();
     // Don't remove links if re-indexing.
     if (!$reindex) {
       db_delete('search_node_links')
         ->condition('sid', $sid)
-        ->condition('type', $type)
+        ->condition('type', $module)
         ->execute();
     }
   }
 }
 
 /**
- * Marks a word as dirty (or retrieves the list of dirty words). This is used
- * during indexing (cron). Words which are dirty have outdated total counts in
- * the search_total table, and need to be recounted.
+ * Marks a word as "dirty" (changed), or retrieves the list of dirty words.
+ *
+ * This is used during indexing (cron). Words that are dirty have outdated
+ * total counts in the search_total table, and need to be recounted.
  */
 function search_dirty($word = NULL) {
   $dirty = &drupal_static(__FUNCTION__, array());
@@ -346,8 +349,9 @@ function search_dirty($word = NULL) {
 /**
  * Implements hook_cron().
  *
- * Fires hook_update_index() in all modules and cleans up dirty words (see
- * search_dirty).
+ * Fires hook_update_index() in all modules and cleans up dirty words.
+ *
+ * @see search_dirty()
  */
 function search_cron() {
   // We register a shutdown function to ensure that search_total is always up
@@ -361,7 +365,9 @@ function search_cron() {
 }
 
 /**
- * This function is called on shutdown to ensure that search_total is always
+ * Updates the {search_total} database table.
+ *
+ * This function is called on shutdown to ensure that {search_total} is always
  * up to date (even if cron times out or otherwise fails).
  */
 function search_update_totals() {
@@ -521,17 +527,16 @@ function search_invoke_preprocess(&$text) {
  * Update the full-text search index for a particular item.
  *
  * @param $sid
- *   A number identifying this particular item (e.g. node id).
- *
- * @param $type
- *   A string defining this type of item (e.g. 'node')
- *
+ *   An ID number identifying this particular item (e.g., node ID).
+ * @param $module
+ *   The machine-readable name of the module that this item comes from (a module
+ *   that implements hook_search_info()).
  * @param $text
- *   The content of this item. Must be a piece of HTML text.
+ *   The content of this item. Must be a piece of HTML or plain text.
  *
  * @ingroup search
  */
-function search_index($sid, $type, $text) {
+function search_index($sid, $module, $text) {
   $minimum_word_size = variable_get('minimum_word_size', 3);
 
   // Link matching
@@ -678,13 +683,13 @@ function search_index($sid, $type, $text) {
     $tag = !$tag;
   }
 
-  search_reindex($sid, $type, TRUE);
+  search_reindex($sid, $module, TRUE);
 
   // Insert cleaned up data into dataset
   db_insert('search_dataset')
     ->fields(array(
       'sid' => $sid,
-      'type' => $type,
+      'type' => $module,
       'data' => $accum,
       'reindex' => 0,
     ))
@@ -699,7 +704,7 @@ function search_index($sid, $type, $text) {
       ->key(array(
         'word' => $word,
         'sid' => $sid,
-        'type' => $type,
+        'type' => $module,
       ))
       ->fields(array('score' => $score))
       ->expression('score', 'score + :score', array(':score' => $score))
@@ -711,7 +716,7 @@ function search_index($sid, $type, $text) {
   // Get all previous links from this item.
   $result = db_query("SELECT nid, caption FROM {search_node_links} WHERE sid = :sid AND type = :type", array(
     ':sid' => $sid,
-    ':type' => $type
+    ':type' => $module
   ), array('target' => 'slave'));
   $links = array();
   foreach ($result as $link) {
@@ -727,7 +732,7 @@ function search_index($sid, $type, $text) {
         db_update('search_node_links')
           ->fields(array('caption' => $caption))
           ->condition('sid', $sid)
-          ->condition('type', $type)
+          ->condition('type', $module)
           ->condition('nid', $nid)
           ->execute();
         search_touch_node($nid);
@@ -735,14 +740,14 @@ function search_index($sid, $type, $text) {
       // Unset the link to mark it as processed.
       unset($links[$nid]);
     }
-    elseif ($sid != $nid || $type != 'node') {
+    elseif ($sid != $nid || $module != 'node') {
       // Insert the existing link and mark the node for reindexing, but don't
       // reindex if this is a link in a node pointing to itself.
       db_insert('search_node_links')
         ->fields(array(
           'caption' => $caption,
           'sid' => $sid,
-          'type' => $type,
+          'type' => $module,
           'nid' => $nid,
         ))
         ->execute();
@@ -753,7 +758,7 @@ function search_index($sid, $type, $text) {
   foreach ($links as $nid => $caption) {
     db_delete('search_node_links')
       ->condition('sid', $sid)
-      ->condition('type', $type)
+      ->condition('type', $module)
       ->condition('nid', $nid)
       ->execute();
     search_touch_node($nid);
@@ -761,10 +766,10 @@ function search_index($sid, $type, $text) {
 }
 
 /**
- * Change a node's changed timestamp to 'now' to force reindexing.
+ * Changes a node's changed timestamp to 'now' to force reindexing.
  *
  * @param $nid
- *   The nid of the node that needs reindexing.
+ *   The node ID of the node that needs reindexing.
  */
 function search_touch_node($nid) {
   db_update('search_dataset')
@@ -904,15 +909,15 @@ function search_expression_insert($expression, $option, $value = NULL) {
  * for all of the search features to work.
  *
  * There are three ways to interact with the search system:
- * - Specifically for searching nodes, you can implement hook_node_update_index()
- *   and hook_node_search_result(). However, note that the search system already
- *   indexes all visible output of a node, i.e. everything displayed normally
- *   by hook_view() and hook_node_view(). This is usually sufficient. You should
- *   only use this mechanism if you want additional, non-visible data to be
- *   indexed.
- * - Implement hook_search_info(). This will create a search tab for your module on
- *   the /search page with a simple keyword search form. You will also need to
- *   implement hook_search_execute() to perform the search.
+ * - Specifically for searching nodes, you can implement
+ *   hook_node_update_index() and hook_node_search_result(). However, note that
+ *   the search system already indexes all visible output of a node; i.e.,
+ *   everything displayed normally by hook_view() and hook_node_view(). This is
+ *   usually sufficient. You should only use this mechanism if you want
+ *   additional, non-visible data to be indexed.
+ * - Implement hook_search_info(). This will create a search tab for your module
+ *   on the /search page with a simple keyword search form. You will also need
+ *   to implement hook_search_execute() to perform the search.
  * - Implement hook_update_index(). This allows your module to use Drupal's
  *   HTML indexing mechanism for searching full text efficiently.
  *
@@ -927,11 +932,11 @@ function search_expression_insert($expression, $option, $value = NULL) {
  *
  * @param $action
  *   Form action. Defaults to "search/$path", where $path is the search path
- *   associated with the $type module in its hook_search_info(). This will be
+ *   associated with the module in its hook_search_info(). This will be
  *   run through url().
  * @param $keys
  *   The search string entered by the user, containing keywords for the search.
- * @param $type
+ * @param $module
  *   The search module to render the form for: a module that implements
  *   hook_search_info(). If not supplied, the default search module is used.
  * @param $prompt
@@ -941,14 +946,14 @@ function search_expression_insert($expression, $option, $value = NULL) {
  * @return
  *   A Form API array for the search form.
  */
-function search_form($form, &$form_state, $action = '', $keys = '', $type = NULL, $prompt = NULL) {
+function search_form($form, &$form_state, $action = '', $keys = '', $module = NULL, $prompt = NULL) {
   $module_info = FALSE;
-  if (!$type) {
+  if (!$module) {
     $module_info = search_get_default_module_info();
   }
   else {
     $info = search_get_info();
-    $module_info = isset($info[$type]) ? $info[$type] : FALSE;
+    $module_info = isset($info[$module]) ? $info[$module] : FALSE;
   }
 
   // Sanity check.
@@ -968,7 +973,7 @@ function search_form($form, &$form_state, $action = '', $keys = '', $type = NULL
   // Record the $action for later use in redirecting.
   $form_state['action'] = $action;
   $form['#attributes']['class'][] = 'search-form';
-  $form['module'] = array('#type' => 'value', '#value' => $type);
+  $form['module'] = array('#type' => 'value', '#value' => $module);
   $form['basic'] = array('#type' => 'container', '#attributes' => array('class' => array('container-inline')));
   $form['basic']['keys'] = array(
     '#type' => 'textfield',
diff --git a/modules/search/search.pages.inc b/modules/search/search.pages.inc
index 607afa97f..c78c60aaf 100644
--- a/modules/search/search.pages.inc
+++ b/modules/search/search.pages.inc
@@ -77,8 +77,9 @@ function search_view($module = NULL, $keys = '') {
  * Process variables for search-results.tpl.php.
  *
  * The $variables array contains the following arguments:
- * - $results
- * - $module
+ * - $results: Search results array.
+ * - $module: Module the search results came from (module implementing
+ *   hook_search_info()).
  *
  * @see search-results.tpl.php
  */
diff --git a/modules/search/search.test b/modules/search/search.test
index 040465103..c7a18ef46 100644
--- a/modules/search/search.test
+++ b/modules/search/search.test
@@ -1184,7 +1184,7 @@ class SearchConfigSettingsForm extends DrupalWebTestCase {
    * Verify that you can disable individual search modules.
    */
   function testSearchModuleDisabling() {
-    // Array of search types to test: 'path' is the search path, 'title' is
+    // Array of search modules to test: 'path' is the search path, 'title' is
     // the tab title, 'keys' are the keywords to search for, and 'text' is
     // the text to assert is on the results page.
     $module_info = array(