Various additions, improvements and fixes to the search documentation.

modules/search.module

@@ -7,9 +7,10 @@
  */
 
 /**
- * Unicode character classes to include in the index.
+ * Matches Unicode character classes to exclude from the search index.
  * See: http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values
  *
+ * The index only contains the following character classes:
  * Lu     Letter, Uppercase
  * Ll     Letter, Lowercase
  * Lt     Letter, Titlecase
@@ -25,7 +26,7 @@
  * Sk     Symbol, Modifier
  * So     Symbol, Other
  *
- * Matches all character classes not in the list above (enclosing marks, punctuation and control codes, spacers).
+ * All character classes not in the list above (enclosing marks, punctuation, control codes and spacers):
  * 'Me', 'Pc', 'Pd', 'Ps', 'Pe', 'Pi', 'Pf', 'Po', 'Zs', 'Zl', 'Zp', 'Cc', 'Cf', 'Cs', 'Co'
  */
 define('PREG_CLASS_SEARCH_EXCLUDE', '\x{0}-\x{23}\x{25}-\x{2a}\x{2c}-\x{2f}\x{3a}\x{3b}\x{3f}\x{40}\x{5b}-\x{5d}\x{5f}\x{7b}\x{7d}\x{7f}-\x{a1}\x{ab}\x{ad}\x{b7}\x{bb}\x{bf}\x{37e}\x{387}\x{488}\x{489}\x{55a}-\x{55f}\x{589}\x{58a}\x{5be}\x{5c0}\x{5c3}\x{5f3}\x{5f4}\x{600}-\x{603}\x{60c}\x{60d}\x{61b}\x{61f}\x{66a}-\x{66d}\x{6d4}\x{6dd}\x{6de}\x{700}-\x{70d}\x{70f}\x{964}\x{965}\x{970}\x{df4}\x{e4f}\x{e5a}\x{e5b}\x{f04}-\x{f12}\x{f3a}-\x{f3d}\x{f85}\x{104a}-\x{104f}\x{10fb}\x{1361}-\x{1368}\x{166d}\x{166e}\x{1680}\x{169b}\x{169c}\x{16eb}-\x{16ed}\x{1735}\x{1736}\x{17b4}\x{17b5}\x{17d4}-\x{17d6}\x{17d8}-\x{17da}\x{1800}-\x{180a}\x{180e}\x{1944}\x{1945}\x{2000}-\x{2043}\x{2045}-\x{2051}\x{2053}\x{2054}\x{2057}\x{205f}-\x{2063}\x{206a}-\x{206f}\x{207d}\x{207e}\x{208d}\x{208e}\x{20dd}-\x{20e0}\x{20e2}-\x{20e4}\x{2329}\x{232a}\x{23b4}-\x{23b6}\x{2768}-\x{2775}\x{27e6}-\x{27eb}\x{2983}-\x{2998}\x{29d8}-\x{29db}\x{29fc}\x{29fd}\x{3000}-\x{3003}\x{3008}-\x{3011}\x{3014}-\x{301f}\x{3030}\x{303d}\x{30a0}\x{30fb}\x{d800}\x{db7f}\x{db80}\x{dbff}\x{dc00}\x{dfff}\x{e000}\x{f8ff}\x{fd3e}\x{fd3f}\x{fe30}-\x{fe52}\x{fe54}-\x{fe61}\x{fe63}\x{fe68}\x{fe6a}\x{fe6b}\x{feff}\x{ff01}-\x{ff03}\x{ff05}-\x{ff0a}\x{ff0c}-\x{ff0f}\x{ff1a}\x{ff1b}\x{ff1f}\x{ff20}\x{ff3b}-\x{ff3d}\x{ff3f}\x{ff5b}\x{ff5d}\x{ff5f}-\x{ff65}\x{fff9}-\x{fffb}\x{10100}\x{10101}\x{1039f}\x{1d173}-\x{1d17a}\x{e0001}\x{e0020}-\x{e007f}\x{f0000}\x{ffffd}\x{100000}');
@@ -136,7 +137,6 @@ function search_admin() {
  *  too.
  * @param $type
  *  (optional) The type of item to wipe.
- *
  */
 function search_wipe($sid = NULL, $type = NULL) {
   if ($type == NULL && $sid == NULL) {
@@ -287,6 +287,8 @@ function search_preprocess(&$text) {
  *
  * @param $text
  *   The content of this item. Must be a piece of HTML text.
+ *
+ * @ingroup search
  */
 function search_index($sid, $type, $text) {
   $minimum_word_size = variable_get('minimum_word_size', 3);
@@ -399,9 +401,10 @@ function search_index($sid, $type, $text) {
 /**
  * Perform a search on a word or words.
  *
- * This function is called by each module that supports the indexed search.
+ * This function is called by each module that supports the indexed search
+ * (and thus, implements hook_update_index()).
  *
- * The end result is an SQL select on the search_index table. As a guide for
+ * The final query is an SQL select on the search_index table. As a guide for
  * writing the optional extra SQL fragments (see below), use this query:
  *
  * SELECT i.type, i.sid, i.word, SUM(i.score/t.count) AS score
@@ -427,6 +430,8 @@ function search_index($sid, $type, $text) {
  *
  * @return
  *   An array of SIDs for the search results.
+ *
+ * @ingroup search
  */
 function do_search($keys, $type, $join = '', $where = '1') {
   // Note, we replace the wildcards with U+FFFD (Replacement character) to pass
@@ -533,27 +538,40 @@ function search_view() {
  * 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
  * 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 nodeapi('update index')
+ *   and nodeapi('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_nodeapi('view'). This is usually sufficient.
+ *   You should only use this mechanism if you want additional, non-visible data
+ *   to be indexed.
+ * - Implement hook_search(). This will create a search tab for your module on
+ *   the /search page with a simple keyword search form. You may optionally
+ *   implement hook_search_item() to customize the display of your results.
+ * - 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
+ * to implement it yourself without hook_search(). In that case, you should 
+ * define it as a local task (tab) under the /search page (e.g. /search/mymodule)
+ * so that users can easily find it.
  */
 
 /**
  * Render a search form.
  *
- * This form must be usable not only within "http://example.com/search", but also
- * as a simple search box (without "Restrict search to", help text, etc.), in the
- * theme's header, and so forth. This means we must provide options to
- * conditionally render certain parts of this form.
- *
  * @param $action
  *   Form action. Defaults to "search".
  * @param $keys
  *   The search string entered by the user, containing keywords for the search.
- * @param $options
- *   Whether to render the optional form fields and text ("Restrict search
- *   to", help text, etc.).
+ * @param $type
+ *   The type of search to render the node for. Must be the name of module
+ *   which implements hook_search(). Defaults to 'node'.
  * @return
  *   An HTML string containing the search form.
  */
-function search_form($action = '', $keys = '', $type = null, $options = FALSE) {
+function search_form($action = '', $keys = '', $type = null) {
   $edit = $_POST['edit'];
 
   if (!$action) {
@@ -598,10 +616,6 @@ function search_data($keys = NULL, $type = 'node') {
   return $output;
 }
 
-/**
- * @} End of "defgroup search".
- */
-
 /**
  * Returns snippets from a piece of text, with certain keywords highlighted.
  * Used for formatting search results.
@@ -707,6 +721,10 @@ function search_excerpt($keys, $text) {
   return $text;
 }
 
+/**
+ * @} End of "defgroup search".
+ */
+
 /**
  * Helper function for array_walk in search_except.
  */
@@ -726,7 +744,9 @@ function _search_excerpt_replace($text) {
  *   Optionally, "extra" can be an array of extra info to show along with the
  *   result.
  * @param $type
- *   The type of item found, such as "user" or "comment".
+ *   The type of item found, such as "user" or "node".
+ *
+ * @ingroup themeable
  */
 function theme_search_item($item, $type) {
   if (module_hook($type, 'search_item')) {

modules/search/search.module

@@ -7,9 +7,10 @@
  */
 
 /**
- * Unicode character classes to include in the index.
+ * Matches Unicode character classes to exclude from the search index.
  * See: http://www.unicode.org/Public/UNIDATA/UCD.html#General_Category_Values
  *
+ * The index only contains the following character classes:
  * Lu     Letter, Uppercase
  * Ll     Letter, Lowercase
  * Lt     Letter, Titlecase
@@ -25,7 +26,7 @@
  * Sk     Symbol, Modifier
  * So     Symbol, Other
  *
- * Matches all character classes not in the list above (enclosing marks, punctuation and control codes, spacers).
+ * All character classes not in the list above (enclosing marks, punctuation, control codes and spacers):
  * 'Me', 'Pc', 'Pd', 'Ps', 'Pe', 'Pi', 'Pf', 'Po', 'Zs', 'Zl', 'Zp', 'Cc', 'Cf', 'Cs', 'Co'
  */
 define('PREG_CLASS_SEARCH_EXCLUDE', '\x{0}-\x{23}\x{25}-\x{2a}\x{2c}-\x{2f}\x{3a}\x{3b}\x{3f}\x{40}\x{5b}-\x{5d}\x{5f}\x{7b}\x{7d}\x{7f}-\x{a1}\x{ab}\x{ad}\x{b7}\x{bb}\x{bf}\x{37e}\x{387}\x{488}\x{489}\x{55a}-\x{55f}\x{589}\x{58a}\x{5be}\x{5c0}\x{5c3}\x{5f3}\x{5f4}\x{600}-\x{603}\x{60c}\x{60d}\x{61b}\x{61f}\x{66a}-\x{66d}\x{6d4}\x{6dd}\x{6de}\x{700}-\x{70d}\x{70f}\x{964}\x{965}\x{970}\x{df4}\x{e4f}\x{e5a}\x{e5b}\x{f04}-\x{f12}\x{f3a}-\x{f3d}\x{f85}\x{104a}-\x{104f}\x{10fb}\x{1361}-\x{1368}\x{166d}\x{166e}\x{1680}\x{169b}\x{169c}\x{16eb}-\x{16ed}\x{1735}\x{1736}\x{17b4}\x{17b5}\x{17d4}-\x{17d6}\x{17d8}-\x{17da}\x{1800}-\x{180a}\x{180e}\x{1944}\x{1945}\x{2000}-\x{2043}\x{2045}-\x{2051}\x{2053}\x{2054}\x{2057}\x{205f}-\x{2063}\x{206a}-\x{206f}\x{207d}\x{207e}\x{208d}\x{208e}\x{20dd}-\x{20e0}\x{20e2}-\x{20e4}\x{2329}\x{232a}\x{23b4}-\x{23b6}\x{2768}-\x{2775}\x{27e6}-\x{27eb}\x{2983}-\x{2998}\x{29d8}-\x{29db}\x{29fc}\x{29fd}\x{3000}-\x{3003}\x{3008}-\x{3011}\x{3014}-\x{301f}\x{3030}\x{303d}\x{30a0}\x{30fb}\x{d800}\x{db7f}\x{db80}\x{dbff}\x{dc00}\x{dfff}\x{e000}\x{f8ff}\x{fd3e}\x{fd3f}\x{fe30}-\x{fe52}\x{fe54}-\x{fe61}\x{fe63}\x{fe68}\x{fe6a}\x{fe6b}\x{feff}\x{ff01}-\x{ff03}\x{ff05}-\x{ff0a}\x{ff0c}-\x{ff0f}\x{ff1a}\x{ff1b}\x{ff1f}\x{ff20}\x{ff3b}-\x{ff3d}\x{ff3f}\x{ff5b}\x{ff5d}\x{ff5f}-\x{ff65}\x{fff9}-\x{fffb}\x{10100}\x{10101}\x{1039f}\x{1d173}-\x{1d17a}\x{e0001}\x{e0020}-\x{e007f}\x{f0000}\x{ffffd}\x{100000}');
@@ -136,7 +137,6 @@ function search_admin() {
  *  too.
  * @param $type
  *  (optional) The type of item to wipe.
- *
  */
 function search_wipe($sid = NULL, $type = NULL) {
   if ($type == NULL && $sid == NULL) {
@@ -287,6 +287,8 @@ function search_preprocess(&$text) {
  *
  * @param $text
  *   The content of this item. Must be a piece of HTML text.
+ *
+ * @ingroup search
  */
 function search_index($sid, $type, $text) {
   $minimum_word_size = variable_get('minimum_word_size', 3);
@@ -399,9 +401,10 @@ function search_index($sid, $type, $text) {
 /**
  * Perform a search on a word or words.
  *
- * This function is called by each module that supports the indexed search.
+ * This function is called by each module that supports the indexed search
+ * (and thus, implements hook_update_index()).
  *
- * The end result is an SQL select on the search_index table. As a guide for
+ * The final query is an SQL select on the search_index table. As a guide for
  * writing the optional extra SQL fragments (see below), use this query:
  *
  * SELECT i.type, i.sid, i.word, SUM(i.score/t.count) AS score
@@ -427,6 +430,8 @@ function search_index($sid, $type, $text) {
  *
  * @return
  *   An array of SIDs for the search results.
+ *
+ * @ingroup search
  */
 function do_search($keys, $type, $join = '', $where = '1') {
   // Note, we replace the wildcards with U+FFFD (Replacement character) to pass
@@ -533,27 +538,40 @@ function search_view() {
  * 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
  * 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 nodeapi('update index')
+ *   and nodeapi('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_nodeapi('view'). This is usually sufficient.
+ *   You should only use this mechanism if you want additional, non-visible data
+ *   to be indexed.
+ * - Implement hook_search(). This will create a search tab for your module on
+ *   the /search page with a simple keyword search form. You may optionally
+ *   implement hook_search_item() to customize the display of your results.
+ * - 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
+ * to implement it yourself without hook_search(). In that case, you should 
+ * define it as a local task (tab) under the /search page (e.g. /search/mymodule)
+ * so that users can easily find it.
  */
 
 /**
  * Render a search form.
  *
- * This form must be usable not only within "http://example.com/search", but also
- * as a simple search box (without "Restrict search to", help text, etc.), in the
- * theme's header, and so forth. This means we must provide options to
- * conditionally render certain parts of this form.
- *
  * @param $action
  *   Form action. Defaults to "search".
  * @param $keys
  *   The search string entered by the user, containing keywords for the search.
- * @param $options
- *   Whether to render the optional form fields and text ("Restrict search
- *   to", help text, etc.).
+ * @param $type
+ *   The type of search to render the node for. Must be the name of module
+ *   which implements hook_search(). Defaults to 'node'.
  * @return
  *   An HTML string containing the search form.
  */
-function search_form($action = '', $keys = '', $type = null, $options = FALSE) {
+function search_form($action = '', $keys = '', $type = null) {
   $edit = $_POST['edit'];
 
   if (!$action) {
@@ -598,10 +616,6 @@ function search_data($keys = NULL, $type = 'node') {
   return $output;
 }
 
-/**
- * @} End of "defgroup search".
- */
-
 /**
  * Returns snippets from a piece of text, with certain keywords highlighted.
  * Used for formatting search results.
@@ -707,6 +721,10 @@ function search_excerpt($keys, $text) {
   return $text;
 }
 
+/**
+ * @} End of "defgroup search".
+ */
+
 /**
  * Helper function for array_walk in search_except.
  */
@@ -726,7 +744,9 @@ function _search_excerpt_replace($text) {
  *   Optionally, "extra" can be an array of extra info to show along with the
  *   result.
  * @param $type
- *   The type of item found, such as "user" or "comment".
+ *   The type of item found, such as "user" or "node".
+ *
+ * @ingroup themeable
  */
 function theme_search_item($item, $type) {
   if (module_hook($type, 'search_item')) {