Issue #1355670 by pwolanin, NROTC_Webmaster, xjm: API docs cleanup for Search module

core/modules/search/lib/Drupal/search/SearchQuery.php

@@ -3,6 +3,8 @@
 /**
  * @file
  * Definition of Drupal\search\SearchQuery.
+ *
+ * Search query extender and helper functions.
  */
 
 namespace Drupal\search;
@@ -11,19 +13,14 @@ use Drupal\Core\Database\Query\SelectExtender;
 use Drupal\Core\Database\StatementEmpty;
 
 /**
- * @file
+ * Performs a query on the full-text search index for a word or words.
- * Search query extender and helper functions.
- */
-
-/**
- * Do a query on the full-text search index for a word or words.
  *
  * This function is normally only called by each module that supports the
  * indexed search (and thus, implements hook_update_index()).
  *
  * Results are retrieved in two logical passes. However, the two passes are
- * joined together into a single query. And in the case of most simple
+ * joined together into a single query, and in the case of most simple queries
- * queries the second pass is not even used.
+ * the second pass is not even used.
  *
  * The first pass selects a set of all possible matches, which has the benefit
  * of also providing the exact result set for simple "AND" or "OR" searches.
@@ -43,7 +40,7 @@ class SearchQuery extends SelectExtender {
   protected $searchExpression;
 
   /**
-   * Type of search (search module).
+   * The type of search (search module).
    *
    * 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
@@ -63,7 +60,7 @@ class SearchQuery extends SelectExtender {
   /**
    * Indicates whether the first pass query requires complex conditions (LIKE).
    *
-   * @var boolean.
+   * @var bool
    */
   protected $simple = TRUE;
 
@@ -107,7 +104,7 @@ class SearchQuery extends SelectExtender {
   /**
    * Indicates whether the first pass query has been executed.
    *
-   * @var boolean
+   * @var bool
    */
   protected $executedFirstPass = FALSE;
 
@@ -138,7 +135,7 @@ class SearchQuery extends SelectExtender {
    * The maximum number of AND/OR combinations exceeded can be configured to
    * avoid Denial-of-Service attacks. Expressions beyond the limit are ignored.
    *
-   * @var boolean
+   * @var bool
    */
   protected $expressionsIgnored = FALSE;
 
@@ -411,6 +408,9 @@ class SearchQuery extends SelectExtender {
    * @param $multiply
    *   If set, the score is multiplied with that value. Search query ensures
    *   that the search scores are still normalized.
+   *
+   * @return object
+   *   The updated query object.
    */
   public function addScore($score, $arguments = array(), $multiply = FALSE) {
     if ($multiply) {

core/modules/search/search.admin.inc

@@ -8,7 +8,7 @@
 use Drupal\Component\Utility\NestedArray;
 
 /**
- * Menu callback: confirm wiping of the index.
+ * Menu callback: Confirms wiping of the index.
  */
 function search_reindex_confirm() {
   return confirm_form(array(), t('Are you sure you want to re-index the site?'),
@@ -16,7 +16,10 @@ function search_reindex_confirm() {
 }
 
 /**
- * Handler for wipe confirmation
+ * Form submission handler for search_reindex_confirm().
+ *
+ * @see search_reindex()
+ * @see search_reindex_confirm()
  */
 function search_reindex_confirm_submit(&$form, &$form_state) {
   if ($form['confirm']) {
@@ -39,13 +42,13 @@ function _search_get_module_names() {
 }
 
 /**
- * Menu callback: displays the search module settings page.
+ * Form constructor for the Search module's settings page.
- *
- * @ingroup forms
  *
  * @see search_admin_settings_validate()
  * @see search_admin_settings_submit()
  * @see search_admin_reindex_submit()
+ *
+ * @ingroup forms
  */
 function search_admin_settings($form, &$form_state) {
   $config = config('search.settings');
@@ -183,7 +186,7 @@ function search_admin_settings_submit($form, &$form_state) {
 }
 
 /**
- * Form submission handler for reindex button on search_admin_settings_form().
+ * Form submission handler for the reindex button on search_admin_settings().
  */
 function search_admin_reindex_submit($form, &$form_state) {
   // send the user to the confirmation page

core/modules/search/search.api.php

@@ -13,28 +13,28 @@
 /**
  * Define a custom search type.
  *
- * This hook allows a module to tell search.module that it wishes to perform
+ * This hook allows a module to tell the Search module that it wishes to
- * searches on content it defines (custom node types, users, or comments for
+ * perform searches on content it defines (custom node types, users, or
- * example) when a site search is performed.
+ * comments for example) when a site search is performed.
  *
  * In order for the search to do anything, your module must also implement
- * hook_search_execute(), which is called when someone requests a search
+ * hook_search_execute(), which is called when someone requests a search on
- * on your module's type of content. If you want to have your content
+ * your module's type of content. If you want to have your content indexed
- * indexed in the standard search index, your module should also implement
+ * 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 use
  * hook_form_FORM_ID_alter(), with FORM_ID set to 'search_form', to add fields
  * to the search form (see node_form_search_form_alter() for an example).
- * You can use hook_search_access() to limit access to searching,
+ * You can use hook_search_access() to limit access to searching, and
- * and hook_search_page() to override how search results are displayed.
+ * hook_search_page() to override how search results are displayed.
  *
  * @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
- *     to the module name if not given.
+ *     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
+ *   - 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
@@ -58,6 +58,7 @@ function hook_search_info() {
  * generated internally - for example based on a module's settings.
  *
  * @see hook_search_info()
+ *
  * @ingroup search
  */
 function sample_search_conditions_callback($keys) {
@@ -90,8 +91,8 @@ function hook_search_access() {
  * Take action when the search index is going to be rebuilt.
  *
  * Modules that use hook_update_index() should update their indexing
- * bookkeeping so that it starts from scratch the next time
+ * bookkeeping so that it starts from scratch the next time hook_update_index()
- * hook_update_index() is called.
+ * is called.
  *
  * @ingroup search
  */
@@ -111,8 +112,8 @@ function hook_search_reset() {
  *
  * @return
  *  An associative array with the key-value pairs:
- *  - 'remaining': The number of items left to index.
+ *  - remaining: The number of items left to index.
- *  - 'total': The total number of items to index.
+ *  - total: The total number of items to index.
  *
  * @ingroup search
  */
@@ -179,22 +180,23 @@ function hook_search_admin() {
  * index.
  *
  * @param $keys
- *   The search keywords as entered by the user.
+ *   The search keywords as entered by the user. Defaults to NULL.
  * @param $conditions
- *   An optional array of additional conditions, such as filters.
+ *   (optional) An array of additional conditions, such as filters. Defaults to
+ *   NULL.
  *
  * @return
- *   An array of search results. To use the default search result
+ *   An array of search results. To use the default search result display, each
- *   display, each item should have the following keys':
+ *   item should have the following keys':
- *   - 'link': Required. The URL of the found item.
+ *   - link: (required) The URL of the found item.
- *   - 'type': The type of item (such as the content type).
+ *   - type: The type of item (such as the content type).
- *   - 'title': Required. The name of the item.
+ *   - title: (required) The name of the item.
- *   - 'user': The author of the item.
+ *   - user: The author of the item.
- *   - 'date': A timestamp when the item was last modified.
+ *   - date: A timestamp when the item was last modified.
- *   - 'extra': An array of optional extra information items.
+ *   - extra: An array of optional extra information items.
- *   - 'snippet': An excerpt or preview to show with the result (can be
+ *   - snippet: An excerpt or preview to show with the result (can be generated
- *     generated with search_excerpt()).
+ *     with search_excerpt()).
- *   - 'language': Language code for the item (usually two characters).
+ *   - language: Language code for the item (usually two characters).
  *
  * @ingroup search
  */
@@ -261,22 +263,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
+ * A module that implements hook_search_info() to define a type of search may
- * may implement this hook in order to override the default theming of
+ * implement this hook in order to override the default theming of its search
- * its search results, which is otherwise themed using theme('search_results').
+ * 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 renderable array, which will render the formatted search results with a
- *   a pager included.
+ *   pager included.
+ *
+ * @see search-result.tpl.php
+ * @see search-results.tpl.php
  */
 function hook_search_page($results) {
   $output['prefix']['#markup'] = '<ol class="search-results">';
@@ -296,8 +299,8 @@ function hook_search_page($results) {
 /**
  * Preprocess text for search.
  *
- * This hook is called to preprocess both the text added to the search index and
+ * This hook is called to preprocess both the text added to the search index
- * the keywords users have submitted for searching.
+ * and the keywords users have submitted for searching.
  *
  * Possible uses:
  * - Adding spaces between words of Chinese or Japanese text.
@@ -314,9 +317,9 @@ function hook_search_page($results) {
  *   The language code of the entity that has been found.
  *
  * @return
- *   The text after preprocessing. Note that if your module decides not to alter
+ *   The text after preprocessing. Note that if your module decides not to
- *   the text, it should return the original text. Also, after preprocessing,
+ *   alter the text, it should return the original text. Also, after
- *   words in the text should be separated by a space.
+ *   preprocessing, words in the text should be separated by a space.
  *
  * @ingroup search
  */
@@ -336,7 +339,7 @@ function hook_search_preprocess($text, $langcode = NULL) {
 /**
  * Update the search index for this module.
  *
- * This hook is called every cron run if search.module is enabled, your
+ * This hook is called every cron run if the 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
@@ -382,6 +385,7 @@ function hook_update_index() {
     search_index($node->nid, 'node', $text);
   }
 }
+
 /**
  * @} End of "addtogroup hooks".
  */

core/modules/search/search.install

@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Install, update and uninstall functions for the search module.
+ * Install, update, and uninstall functions for the Search module.
  */
 
 /**

core/modules/search/search.module

@@ -277,14 +277,22 @@ function search_get_default_module_info() {
 }
 
 /**
- * Access callback for search tabs.
+ * Access callback: Determines access for a search page.
+ *
+ * @param int $name
+ *   The name of a search module (e.g., 'node')
+ *
+ * @return bool
+ *   TRUE if a user has access to the search page; FALSE otherwise.
+ *
+ * @see search_menu()
  */
 function _search_menu_access($name) {
   return user_access('search content') && (!function_exists($name . '_search_access') || module_invoke($name, 'search_access'));
 }
 
 /**
- * Clears a part of or the entire search index.
+ * Clears either a part of, or the entire search index.
  *
  * @param $sid
  *   (optional) The ID of the item to remove from the search index. If
@@ -460,14 +468,14 @@ function search_simplify($text, $langcode = NULL) {
  * written in long strings of characters, though, not split up into words. So
  * in order to allow search matching, we split up CJK text into tokens
  * consisting of consecutive, overlapping sequences of characters whose length
- * is equal to the 'minimum_word_size' variable. This tokenizing is only done if
+ * is equal to the 'minimum_word_size' variable. This tokenizing is only done
- * the 'overlap_cjk' variable is TRUE.
+ * if the 'overlap_cjk' variable is TRUE.
  *
  * @param $matches
  *   This function is a callback for preg_replace_callback(), which is called
  *   from search_simplify(). So, $matches is an array of regular expression
- *   matches, which means that $matches[0] contains the matched text -- a string
+ *   matches, which means that $matches[0] contains the matched text -- a
- *   of CJK characters to tokenize.
+ *   string of CJK characters to tokenize.
  *
  * @return
  *   Tokenized text, starting and ending with a space character.
@@ -539,13 +547,13 @@ function search_invoke_preprocess(&$text, $langcode = NULL) {
 }
 
 /**
- * Update the full-text search index for a particular item.
+ * Updates the full-text search index for a particular item.
  *
  * @param $sid
  *   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
+ *   The machine-readable name of the module that this item comes from (a
- *   that implements hook_search_info()).
+ *   module that implements hook_search_info()).
  * @param $text
  *   The content of this item. Must be a piece of HTML or plain text.
  * @param $langcode
@@ -882,13 +890,13 @@ function search_expression_extract($expression, $option) {
  *   The value to add for the option. If present, it will replace any previous
  *   value added for the option. Cannot contain any spaces or | characters, as
  *   these are used as delimiters. If you want to add a blank value $option: to
- *   the search expression, pass in an empty string or a string that is composed
+ *   the search expression, pass in an empty string or a string that is
- *   of only spaces. To clear a previously-stored option without adding a
+ *   composed of only spaces. To clear a previously-stored option without
- *   replacement, pass in NULL for $value or omit.
+ *   adding a replacement, pass in NULL for $value or omit.
  *
  * @return
- *   $expression, with any previous value for this option removed, and a new
+ *   The search expression, with any previous value for this option removed, and
- *   $option:$value pair added if $value was provided.
+ *   a new $option:$value pair added if $value was provided.
  */
 function search_expression_insert($expression, $option, $value = NULL) {
   // Remove any previous values stored with $option.
@@ -907,8 +915,8 @@ function search_expression_insert($expression, $option, $value = NULL) {
  * The Drupal search interface manages a global search mechanism.
  *
  * Modules may plug into this system to provide searches of different types of
- * data. Most of the system is handled by search.module, so this must be enabled
+ * data. Most of the system is handled by the Search module, so this must be
- * for all of the search features to work.
+ * enabled 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
@@ -917,20 +925,20 @@ function search_expression_insert($expression, $option, $value = NULL) {
  *   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
+ * - Implement hook_search_info(). This will create a search tab for your
- *   on the /search page with a simple keyword search form. You will also need
+ *   module on the /search page with a simple keyword search form. You will
- *   to implement hook_search_execute() to perform the search.
+ *   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.
  *
- * If your module needs to provide a more complicated search form, then you need
+ * If your module needs to provide a more complicated search form, then you
- * to implement it yourself without hook_search_info(). In that case, you should
+ * need to implement it yourself without hook_search_info(). In that case, you
- * define it as a local task (tab) under the /search page (e.g. /search/mymodule)
+ * should define it as a local task (tab) under the /search page (e.g.
- * so that users can easily find it.
+ * /search/mymodule) so that users can easily find it.
  */
 
 /**
- * Builds a search form.
+ * Form constructor for the search form.
  *
  * @param $action
  *   Form action. Defaults to "search/$path", where $path is the search path
@@ -942,11 +950,14 @@ function search_expression_insert($expression, $option, $value = NULL) {
  *   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
- *   Label for the keywords field. Defaults to t('Enter your keywords') if NULL.
+ *   Label for the keywords field. Defaults to t('Enter your keywords') if
- *   Supply '' to omit.
+ *   NULL. Supply '' to omit.
  *
  * @return
  *   A Form API array for the search form.
+ *
+ * @see search_form_validate()
+ * @see search_form_submit()
  */
 function search_form($form, &$form_state, $action = '', $keys = '', $module = NULL, $prompt = NULL) {
   $module_info = FALSE;
@@ -992,10 +1003,14 @@ function search_form($form, &$form_state, $action = '', $keys = '', $module = NU
 }
 
 /**
- * Form builder; Output a search form for the search block's search box.
+ * Form constructor for the search block's search box.
+ *
+ * @param $form_id
+ *   The unique string identifying the desired form.
+ *
+ * @see search_box_form_submit()
  *
  * @ingroup forms
- * @see search_box_form_submit()
  */
 function search_box($form, &$form_state, $form_id) {
   $form[$form_id] = array(
@@ -1014,7 +1029,7 @@ function search_box($form, &$form_state, $form_id) {
 }
 
 /**
- * Process a block search form submission.
+ * Form submission handler for search_box().
  */
 function search_box_form_submit($form, &$form_state) {
   // The search form relies on control of the redirect destination for its
@@ -1076,6 +1091,7 @@ function search_data($keys, $module, $conditions = NULL) {
 
 /**
  * Returns snippets from a piece of text, with certain keywords highlighted.
+ *
  * Used for formatting search results.
  *
  * @param $keys
@@ -1232,7 +1248,7 @@ function _search_excerpt_replace(&$text) {
 }
 
 /**
- * Find words in the original text that matched via search_simplify().
+ * Finds words in the original text that matched via search_simplify().
  *
  * This is called in search_excerpt() if an exact match is not found in the
  * text, so that we can find the derived form that matches.

core/modules/search/search.pages.inc

@@ -2,11 +2,11 @@
 
 /**
  * @file
- * User page callbacks for the search module.
+ * User page callbacks for the Search module.
  */
 
 /**
- * Menu callback; presents the search form and/or search results.
+ * Page callback: Presents the search form and/or search results.
  *
  * @param $module
  *   Search module to use for the search.
@@ -72,11 +72,12 @@ function search_view($module = NULL, $keys = '') {
 }
 
 /**
- * Process variables for search-results.tpl.php.
+ * Prepocesses the variables for search-results.tpl.php.
  *
- * The $variables array contains the following arguments:
+ * @param $variables
- * - $results: Search results array.
+ *   An array with the following elements:
- * - $module: Module the search results came from (module implementing
+ *   - results: Search results array.
+ *   - module: Module the search results came from (module implementing
  *     hook_search_info()).
  *
  * @see search-results.tpl.php
@@ -94,11 +95,13 @@ function template_preprocess_search_results(&$variables) {
 }
 
 /**
- * Process variables for search-result.tpl.php.
+ * Preprocesses the variables for search-result.tpl.php.
  *
- * The $variables array contains the following arguments:
+ * @param $variables
- * - $result
+ *   An array with the following elements:
- * - $module
+ *   - result: Search results array.
+ *   - module: Module the search results came from (module implementing
+ *     hook_search_info()).
  *
  * @see search-result.tpl.php
  */
@@ -135,17 +138,23 @@ function template_preprocess_search_result(&$variables) {
 }
 
 /**
+ * Form validation handler for search_form().
+ *
  * As the search form collates keys from other modules hooked in via
- * hook_form_alter, the validation takes place in _submit.
+ * hook_form_alter, the validation takes place in search_form_submit().
  * search_form_validate() is used solely to set the 'processed_keys' form
  * value for the basic search form.
+ *
+ * @see search_form_submit()
  */
 function search_form_validate($form, &$form_state) {
   form_set_value($form['basic']['processed_keys'], trim($form_state['values']['keys']), $form_state);
 }
 
 /**
- * Process a search form submission.
+ * Form submission handler for search_form().
+ *
+ * @see search_form_validate()
  */
 function search_form_submit($form, &$form_state) {
   $keys = $form_state['values']['processed_keys'];

core/modules/search/templates/search-result.tpl.php

@@ -5,8 +5,8 @@
  * Default theme implementation for displaying a single search result.
  *
  * This template renders a single search result and is collected into
- * search-results.tpl.php. This and the parent template are
+ * search-results.tpl.php. This and the parent template are dependent on one
- * dependent to one another sharing the markup for definition lists.
+ * another sharing the markup for definition lists.
  *
  * Available variables:
  * - $url: URL of the result.
@@ -15,8 +15,8 @@
  * - $info: String of all the meta information ready for print. Does not apply
  *   to user searches.
  * - $info_split: Contains same data as $info, split into a keyed array.
- * - $module: The machine-readable name of the module (tab) being searched, such
+ * - $module: The machine-readable name of the module (tab) being searched,
- *   as "node" or "user".
+ *   such as "node" or "user".
  * - $title_prefix (array): An array containing additional output populated by
  *   modules, intended to be displayed in front of the main title tag that
  *   appears in the template.
@@ -30,7 +30,7 @@
  *   on permission.
  * - $info_split['date']: Last update of the node. Short formatted.
  * - $info_split['comment']: Number of comments output as "% comments", %
- *   being the count. Depends on comment.module.
+ *   being the count. Depends on the Comment module.
  *
  * Other variables:
  * - $title_attributes: Array of HTML attributes for the title. It is

core/modules/search/tests/modules/search_embedded_form/search_embedded_form.info

@@ -1,5 +1,5 @@
-name = "Search embedded form"
+name = Search Embedded Form
-description = "Support module for search module testing of embedded forms."
+description = Support module for Search module testing of embedded forms.
 package = Testing
 version = VERSION
 core = 8.x

core/modules/search/tests/modules/search_embedded_form/search_embedded_form.module

@@ -4,9 +4,9 @@
  * @file
  * Test module implementing a form that can be embedded in search results.
  *
- * Embedded form are important, for example, for ecommerce sites where each
+ * A sample use of an embedded form is an e-commerce site where each search
- * search result may included an embedded form with buttons like "Add to cart"
+ * result may include an embedded form with buttons like "Add to cart" for each
- * for each individual product (node) listed in the search results.
+ * individual product (node) listed in the search results.
  */
 
 /**
@@ -25,7 +25,7 @@ function search_embedded_form_menu() {
 }
 
 /**
- * Builds a form for embedding in search results for testing.
+ * Form constructor for embedding search results for testing.
  *
  * @see search_embedded_form_form_submit().
  */

core/modules/search/tests/modules/search_extra_type/search_extra_type.info

@@ -1,5 +1,5 @@
-name = "Test search type"
+name = Test Search Type
-description = "Support module for search module testing."
+description = Support module for Search module testing.
 package = Testing
 version = VERSION
 core = 8.x

core/modules/search/tests/modules/search_extra_type/search_extra_type.module

@@ -17,7 +17,7 @@ function search_extra_type_search_info() {
 }
 
 /**
- * Test conditions callback for hook_search_info().
+ * Tests the conditions callback for hook_search_info().
  */
 function search_extra_type_conditions() {
   $conditions = array();