From 06045ff7fcd44626185548fc886b9e5e5d7e867e Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Mon, 24 Nov 2003 22:46:03 +0000
Subject: [PATCH] Patch by Ax to fixe and improve to the core doxygen PHPdoc:

  * fixes all doxygen warnings [#]_ in the current code base
    + changes @param style from phpDocumentor (@param type $var desc) to doxygen (@param $var desc)
    + documents all undocumented parameters
    + escapes / fixes html warnings
    + fixes @defgroup in theme.inc
  * adds more groupings [#]_
    + drupal_{set|get}_title, drupal_{set|get}_breadcrumb
    + pager.inc: pager_api (pager_query(), pager_display()), pager pieces
  * adds a new group "themeable" which contains all themeable functions.
---
 CHANGELOG                        |   5 +-
 includes/common.inc              |  16 ++-
 includes/database.mysql.inc      |  11 +-
 includes/database.pear.inc       |  10 +-
 includes/pager.inc               | 193 ++++++++++++++++++-------------
 includes/theme.inc               | 136 +++-------------------
 modules/block.module             |   6 +-
 modules/block/block.module       |   6 +-
 modules/search.module            |  27 ++---
 modules/search/search.module     |  27 ++---
 modules/taxonomy.module          |  10 +-
 modules/taxonomy/taxonomy.module |  10 +-
 12 files changed, 193 insertions(+), 264 deletions(-)

diff --git a/CHANGELOG b/CHANGELOG
index ffa7e9b9edf..3ce54860204 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -14,9 +14,12 @@ Drupal x.x.x, xxxx-xx-xx
 - usability:
     * added breadcrumb navigation to all pages.
     * made it possible to add context-sensitive help to all pages.
-    * grouped form elements using '<fieldset>' and '<legend>' tags.
     * replaced drop-down menus by radio buttons where appropriate.
     * removed the 'magic_quotes_gpc = 0' requirement.
+- accessibility:
+    * made themes degrade gracefully in absence of CSS.
+    * grouped form elements using '<fieldset>' and '<legend>' tags.
+    * added '<label>' tags to form elements.
 - documentation:
     * added PHPDoc/Doxygen comments.
 
diff --git a/includes/common.inc b/includes/common.inc
index aaa95276c3c..5e4fa290cb5 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -2,7 +2,9 @@
 // $Id$
 
 /**
+ * @name drupal_title
  * Functions to get and set the title of the current page.
+ * @{
  */
 function drupal_set_title($title = NULL) {
   static $stored_title;
@@ -22,12 +24,14 @@ function drupal_get_title() {
 
   return $title;
 }
-
+// @}
 
 /**
+ * @name drupal_breadcrumb
  * Functions to get and set the breadcrumb trail of the current page. The
  * breadcrumb trail is represented as an array of links, starting with
  * "home" and proceeding up to but not including the current page.
+ * @{
  */
 function drupal_set_breadcrumb($breadcrumb = NULL) {
   static $stored_breadcrumb;
@@ -48,7 +52,7 @@ function drupal_get_breadcrumb() {
 
   return $breadcrumb;
 }
-
+// @}
 
 /**
  * Build the alias/path array
@@ -249,9 +253,9 @@ function valid_url($url) {
 /**
  * Format a single result entry of a search query:
  *
- * @param $item  a single search result as returned by <module>_search of type
- *               array("count" => ..., "link" => ..., "title" => ...,
- *               "user" => ..., "date" => ..., "keywords" => ...)
+ * @param $item  a single search result as returned by <i>module</i>_search of
+ *   type array("count" => ..., "link" => ..., "title" => ..., "user" => ...,
+ *              "date" => ..., "keywords" => ...)
  * @param $type  module type of this item
  */
 function search_item($item, $type) {
@@ -344,7 +348,7 @@ function search_data($keys = NULL) {
  * @param $type    If set, search only nodes of this type.
  *                 Otherwise, search all types.
  * @param $action  Form action. Defaults to 'site.com/search'.
- * @param $query   Query string. Defaults to global $keys.
+ * @param $keys    Query string. Defaults to global $keys.
  * @param $options != 0: Render additional form fields/text
  *                 ("Restrict search to", help text, etc).
  */
diff --git a/includes/database.mysql.inc b/includes/database.mysql.inc
index 7b5dabb8439..2f27a7a5e24 100644
--- a/includes/database.mysql.inc
+++ b/includes/database.mysql.inc
@@ -21,6 +21,12 @@ function db_connect($url) {
   */
 }
 
+/**
+ * Runs a query in the database.
+ *
+ * @param   $query  SQL query, followed by a variable number of arguments which are substituted into query by sprintf.
+ * @return  a MySQL result or FALSE if the query was not executed correctly.
+ */
 function db_query($query) {
   $args = func_get_args();
 
@@ -142,9 +148,8 @@ function db_affected_rows() {
 /**
  * Runs a LIMIT query in the database.
  *
- * @param   mixed     $query  SQL query, followed by a variable number of arguments which are substituted into query by sprintf, followed by 'from' and 'count'  parameters.  'from' is the row to start fetching, 'count' the numbers of rows to fetch.
- * @return  resource  a MySQL result or FALSE if the query was not executed correctly.
- * @access  public
+ * @param   $query  SQL query, followed by a variable number of arguments which are substituted into query by sprintf, followed by 'from' and 'count'  parameters.  'from' is the row to start fetching, 'count' the numbers of rows to fetch.
+ * @return  a MySQL result or FALSE if the query was not executed correctly.
  */
 function db_query_range($query) {
   $args = func_get_args();
diff --git a/includes/database.pear.inc b/includes/database.pear.inc
index c0cd965ea4b..ded3bcf96b2 100644
--- a/includes/database.pear.inc
+++ b/includes/database.pear.inc
@@ -18,9 +18,8 @@ function db_connect($url) {
 /**
  * Runs a query in the database.
  *
- * @param  $query SQL query
- * @param  $type  module type of this item
- * @return sql    result resource
+ * @param   $query  SQL query, followed by a variable number of arguments which are substituted into query by sprintf.
+ * @return  a DB_Result object or a DB_Error
  */
 function db_query($query) {
 
@@ -146,9 +145,8 @@ function db_affected_rows() {
 /**
  * Runs a LIMIT query in the database.
  *
- * @param   mixed   $query  SQL query followed by a variable number of arguments which are substituted into query by sprintf, followed by 'from' and 'count' parameters. 'from' is the row to start fetching, 'count' the numbers of rows to fetch.
- * @return  mixed   a DB_Result object or a DB_Error
- * @access public
+ * @param   $query  SQL query followed by a variable number of arguments which are substituted into query by sprintf, followed by 'from' and 'count' parameters. 'from' is the row to start fetching, 'count' the numbers of rows to fetch.
+ * @return  a DB_Result object or a DB_Error
  */
 function db_query_range($query) {
   global $db_handle, $queries;
diff --git a/includes/pager.inc b/includes/pager.inc
index 602f6e78a66..9f371e9bf02 100644
--- a/includes/pager.inc
+++ b/includes/pager.inc
@@ -1,24 +1,84 @@
 <?php
 // $Id$
 
-/* ***************************************************
- *            external functions (API)
- * ***************************************************/
+/**
+  @defgroup pager_api Pager API
+  @{
+
+  Pager external functions (API).
+ **/
+
+/**
+ * Use this function when doing select queries you wish to be able to page.
+ * The pager uses LIMIT-based queries to fetch only the records required
+ * to render a certain page.  However, it has to learn the total number
+ * of records returned by the query to (among others) compute the number
+ * of pages (= number of all records / number of records per page).  This
+ * is done by inserting "COUNT(*)" in the original query, ie. by rewriting
+ * the original query, say "SELECT nid, type FROM node WHERE status = '1'
+ * ORDER BY static DESC, created DESC" to read "SELECT COUNT(*) FROM node
+ * WHERE status = '1' ORDER BY static DESC, created DESC".  Rewriting the
+ * query is accomplished using a regular expression.
+ *
+ * Unfortunately, the rewrite rule does not always work as intended for
+ * queries that (already) have a "COUNT(*)" or a "GROUP BY" clause, and
+ * possibly for other complex queries.  In those cases, you can optionally
+ * pass a query that will be used to count the records.
+ *
+ * For example, if you want to page this query: "SELECT COUNT(*), TYPE FROM
+ * node GROUP BY TYPE", pager_query() would invoke the wrong query, being:
+ * "SELECT COUNT(*) FROM node GROUP BY TYPE".  So instead, you should pass
+ * "SELECT COUNT(DISTINCT(TYPE)) FROM node" as the optional $count_query
+ * parameter.
+ *
+ * @param   $query        the SQL query that needs paging
+ * @param   $limit        the number of rows per page
+ * @param   $element      optional attribute to distringuish between multiple pagers on one page
+ * @param   $count_query  an optional SQL query used to count records when rewriting the query would fail
+ *
+ * @return  SQL query result
+ */
+function pager_query($query, $limit = 10, $element = 0, $count_query = "") {
+  global $pager_from_array, $pager_total;
+  $from = $_GET["from"];
+
+  // count the total number of records in this query:
+  if ($count_query == "") {
+    $pager_total[$element] = db_result(db_query(preg_replace(array("/SELECT.*FROM/i", "/ORDER BY .*/"), array("SELECT COUNT(*) FROM", ""), $query)));
+
+  }
+  else {
+    $pager_total[$element] = db_result(db_query($count_query));
+  }
+
+  // convert comma separated $from to an array, used by other functions:
+  $pager_from_array = explode(",", $from);
+
+  return db_query_range($query, (int)$pager_from_array[$element], (int)$limit);
+
+}
 
 /**
  * Use this function in your module or theme to display a pager.
  *
- * @param   array   $tags     defines your buttons; text or img.
- * @param   int     $limit    how many nodes are displayed per page
- * @param   int     $element  support for multiple pagers per page (specify which this is)
- * @param   string  $type     allows for distinction between pagers on main page and admin page, etc.
+ * @param   $tags     defines your buttons; text or img.
+ * @param   $limit    how many nodes are displayed per page
+ * @param   $element  support for multiple pagers per page (specify which this is)
+ * @param   $type     allows for distinction between pagers on main page and admin page, etc.
  *   Supported types are "default", "admin" and "simple".
+ * @param   $attributes   extra html attributes for \<a href> (eg. title, onMouseOver, etc.)
  *
  * @return  string  html of pager
  */
 function pager_display($tags = "", $limit = 10, $element = 0, $type = "default", $attributes = array()) {
   return theme("pager_display_". $type, $tags, $limit, $element, $attributes);
 }
+/**  @} End of defgroup pager_api **/
+
+/**
+ * @addtogroup themeable
+ * @{
+ */
 
 /**
  * DEFAULT PAGER:
@@ -76,18 +136,24 @@ function theme_pager_display_admin($tags = "", $limit = 10, $element = 0, $attri
   */
   return theme_pager_display_default($tags, $limit, $element, $attributes);
 }
+/**  @} End of addtogroup themeable **/
 
-/* *******************************************************************
- * PAGER PIECES:
- *  Use these pieces to construct your own custom pagers (i.e. in
- *  themes).  Note that you should NOT modify this file to customize
- *  your pager)
- * *******************************************************************/
+/**
+ * @name pager pieces
+ * Use these pieces to construct your own custom pagers in your theme.  Note
+ * that you should NOT modify this file to customize your pager.
+ * @{
+ */
 
 /**
  * displays a "first-page" link
  *
- * @see pager_previous
+ * @param   $text     defines the name (or image) of the link
+ * @param   $limit    how many nodes are displayed per page
+ * @param   $element  distinguish between multiple pagers on one page
+ * @param   $attributes   extra html attributes for \<a href> (eg. title, onMouseOver, etc.)
+ *
+ * @return  string  html of this pager piece
  */
 function pager_first($text, $limit, $element = 0, $attributes = array()) {
   global $pager_from_array;
@@ -104,10 +170,11 @@ function pager_first($text, $limit, $element = 0, $attributes = array()) {
 /**
  * displays a "previous-page" link
  *
- * @param   string  $text     defines the name (or image) of the link
- * @param   int     $limit    how many nodes are displayed per page
- * @param   int     $element  distinguish between multiple pagers on one page
- * @param   int     $n        how many pages we move back (defaults to 1)
+ * @param   $text     defines the name (or image) of the link
+ * @param   $limit    how many nodes are displayed per page
+ * @param   $element  distinguish between multiple pagers on one page
+ * @param   $n        how many pages we move back (defaults to 1)
+ * @param   $attributes   extra html attributes for \<a href> (eg. title, onMouseOver, etc.)
  *
  * @return  string  html of this pager piece
  */
@@ -123,7 +190,13 @@ function pager_previous($text, $limit, $element = 0, $n = 1, $attributes = array
 /**
  * displays a "next-page" link
  *
- * @see pager_previous
+ * @param   $text     defines the name (or image) of the link
+ * @param   $limit    how many nodes are displayed per page
+ * @param   $element  distinguish between multiple pagers on one page
+ * @param   $n        how many pages we move back (defaults to 1)
+ * @param   $attributes   extra html attributes for \<a href> (eg. title, onMouseOver, etc.)
+ *
+ * @return  string  html of this pager piece
  */
 function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array()) {
   global $pager_from_array, $pager_total;
@@ -137,7 +210,12 @@ function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array())
 /**
  * displays a "last-page" link
  *
- * @see pager_previous
+ * @param   $text     defines the name (or image) of the link
+ * @param   $limit    how many nodes are displayed per page
+ * @param   $element  distinguish between multiple pagers on one page
+ * @param   $attributes   extra html attributes for \<a href> (eg. title, onMouseOver, etc.)
+ *
+ * @return  string  html of this pager piece
  */
 function pager_last($text, $limit, $element = 0, $attributes = array()) {
   global $pager_from_array, $pager_total;
@@ -155,8 +233,11 @@ function pager_last($text, $limit, $element = 0, $attributes = array()) {
 /**
  * displays "%d through %d of $d" type detail about the cur page
  *
- * @param   string  $format   allows you to reword the format string
- * @see pager_previous
+ * @param   $limit    how many nodes are displayed per page
+ * @param   $element  distinguish between multiple pagers on one page
+ * @param   $format   allows you to reword the format string
+ *
+ * @return  string  html of this pager piece
  */
 function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") {
   global $pager_from_array, $pager_total;
@@ -171,9 +252,13 @@ function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") {
 /**
  * displays a list of nearby pages with additional nodes
  *
- * @param   int     $quantity   defines the length of the page list
- * @param   string  $text       optional text to display before the page list
- * @see pager_previous
+ * @param   $limit      how many nodes are displayed per page
+ * @param   $element    distinguish between multiple pagers on one page
+ * @param   $quantity   defines the length of the page list
+ * @param   $text       optional text to display before the page list
+ * @param   $attributes   extra html attributes for \<a href> (eg. title, onMouseOver, etc.)
+ *
+ * @return  string  html of this pager piece
  */
 function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes = array()) {
   global $pager_from_array, $pager_total;
@@ -243,63 +328,7 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes
 
   return $output;
 }
-
-
-/* ********************************************************************
- * QUERIES - call this instead of db_query() if you want your query to
- * support a pager.
- * ********************************************************************/
-
-/**
- * Use this function when doing select queries you wish to be able to page.
- * The pager uses LIMIT-based queries to fetch only the records required
- * to render a certain page.  However, it has to learn the total number
- * of records returned by the query to (among others) compute the number
- * of pages (= number of all records / number of records per page).  This
- * is done by inserting "COUNT(*)" in the original query, ie. by rewriting
- * the original query, say "SELECT nid, type FROM node WHERE status = '1'
- * ORDER BY static DESC, created DESC" to read "SELECT COUNT(*) FROM node
- * WHERE status = '1' ORDER BY static DESC, created DESC".  Rewriting the
- * query is accomplished using a regular expression.
- *
- * Unfortunately, the rewrite rule does not always work as intended for
- * queries that (already) have a "COUNT(*)" or a "GROUP BY" clause, and
- * possibly for other complex queries.  In those cases, you can optionally
- * pass a query that will be used to count the records.
- *
- * For example, if you want to page this query: "SELECT COUNT(*), TYPE FROM
- * node GROUP BY TYPE", pager_query() would invoke the wrong query, being:
- * "SELECT COUNT(*) FROM node GROUP BY TYPE".  So instead, you should pass
- * "SELECT COUNT(DISTINCT(TYPE)) FROM node" as the optional $count_query
- * parameter.
- *
- * @param   string  $query        the SQL query that needs paging
- * @param   int     $limit        the number of rows per page
- * @param   int     $element      optional attribute to distringuish between multiple pagers on one page
- * @param   string  $count_query  an optional SQL query used to count records when rewriting the query would fail
- *
- * @return  resource  SQL query result
- */
-
-function pager_query($query, $limit = 10, $element = 0, $count_query = "") {
-  global $pager_from_array, $pager_total;
-  $from = $_GET["from"];
-
-  // count the total number of records in this query:
-  if ($count_query == "") {
-    $pager_total[$element] = db_result(db_query(preg_replace(array("/SELECT.*FROM/i", "/ORDER BY .*/"), array("SELECT COUNT(*) FROM", ""), $query)));
-
-  }
-  else {
-    $pager_total[$element] = db_result(db_query($count_query));
-  }
-
-  // convert comma separated $from to an array, used by other functions:
-  $pager_from_array = explode(",", $from);
-
-  return db_query_range($query, (int)$pager_from_array[$element], (int)$limit);
-
-}
+/* @} End of member group pager pieces */
 
 function pager_link($from_new, $attributes = array()) {
   $q = $_GET["q"];
diff --git a/includes/theme.inc b/includes/theme.inc
index 2c2c8dba3df..8d6f844683e 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -128,29 +128,6 @@ function theme_node($node, $main) {
   return $output;
 }
 
-function _theme_table_cell($cell, $header = 0) {
-  if (is_array($cell)) {
-    $data = $cell["data"];
-    foreach ($cell as $key => $value) {
-      if ($key != "data")  {
-        $attributes .= " $key=\"$value\"";
-      }
-    }
-  }
-  else {
-    $data = $cell;
-  }
-
-  if ($header) {
-    $output = "<th$attributes>$data</th>";
-  }
-  else {
-    $output = "<td$attributes>$data</td>";
-  }
-
-  return $output;
-}
-
 /**
   Returns themed table.
 
@@ -331,7 +308,7 @@ function theme_head($main = 0) {
 
 /**
   Execute hook _footer() which is run at the end of the page right
-  before the </body> tag.
+  before the \</body> tag.
 
   @param $main (optional)
 
@@ -381,109 +358,28 @@ function theme_blocks($region) {
   }
   return $output;
 }
+/**  @} End of defgroup themeable **/
 
-/**
-  Hook Help - returns theme specific help and information.
-
-  @param section defines the \a section of the help to be returned.
-
-  @return a string containing the help output.
-**/
-function theme_help($section) {
-  $ouptout = "";
-
-  switch ($section) {
-    case 'admin/system/themes#description':
-      $output = t("The base theme");
-      break;
-  }
-  return $output;
-}
-
-/**
-  Provides a list of currently available themes.
-
-  @param $refresh
-
-  @return an array of the currently available themes.
-**/
-function list_themes($refresh = 0) {
-  static $list;
-
-  if ($refresh) {
-    unset($list);
-  }
-
-  if (!$list) {
-    $list = array();
-    $result = db_query("SELECT * FROM {system} where type = 'theme' AND status = '1' ORDER BY name");
-    while ($theme = db_fetch_object($result)) {
-      if (file_exists($theme->filename)) {
-        $list[$theme->name] = $theme;
+function _theme_table_cell($cell, $header = 0) {
+  if (is_array($cell)) {
+    $data = $cell["data"];
+    foreach ($cell as $key => $value) {
+      if ($key != "data")  {
+        $attributes .= " $key=\"$value\"";
       }
     }
   }
-
-  return $list;
-}
-
-/**
-  Initialized the theme system.
-
-  @return the name of the currently selected theme.
-**/
-function init_theme() {
-  global $user;
-
-  $themes = list_themes();
-  $name = $user->theme ? $user->theme : variable_get("theme_default", 0);
-
-  $theme->path = "";
-  $theme->name = "";
-
-  if (is_object($themes[$name])) {
-    include_once($themes[$name]->filename);
-    $theme->path = dirname($themes[$name]->filename);
-    $theme->name = $name;
+  else {
+    $data = $cell;
   }
 
-  return $theme;
-}
-
-/**
-  Returns the path to the currently selected theme.
-
-  @return the path to the the currently selected theme.
-**/
-function path_to_theme() {
-  global $theme;
-  return $theme->path;
-}
-
-/**
-  External interface of the theme system to all other modules, and core files.
-
-  All requests for themed functions must go through this function. It examines
-  the request and routes it to the appropriate theme function. If the current
-  theme does not implement the requested function, then the base theme function
-  is called.
-  Example: \verbatim $header_text = theme("header"); \endverbatim
-
-  @return the path to the the currently selected theme.
-**/
-function theme() {
-  global $theme;
-
-  $args = func_get_args();
-  $function = array_shift($args);
-
-  if (($theme->name != "") && (function_exists($theme->name ."_". $function))) {
-    return call_user_func_array($theme->name ."_". $function, $args);
+  if ($header) {
+    $output = "<th$attributes>$data</th>";
   }
-  elseif (function_exists("theme_". $function)){
-    return call_user_func_array("theme_". $function, $args);
+  else {
+    $output = "<td$attributes>$data</td>";
   }
-}
 
-/**  @} End of defgroup theme_system **/
+  return $output;
+}
 ?>
diff --git a/modules/block.module b/modules/block.module
index df91c0cb6d6..1ae85956609 100644
--- a/modules/block.module
+++ b/modules/block.module
@@ -103,9 +103,9 @@ function block_admin_save($edit) {
 /**
  * update blocks db table with blocks currently exported by modules
  *
- * @param   array   $order_by   php array_multisort() style sort ordering, eg. "weight", SORT_ASC, SORT_STRING. see {@link http://www.php.net/manual/en/function.array-multisort.php}
- * @return  array   blocks currently exported by modules, sorted by $order_by
- * @access  private
+ * @param   $order_by   php <a href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a> style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
+ *
+ * @return  blocks currently exported by modules, sorted by $order_by
  */
 function _block_rehash($order_by = array("weight")) {
   $result = db_query("SELECT * FROM {blocks} ");
diff --git a/modules/block/block.module b/modules/block/block.module
index df91c0cb6d6..1ae85956609 100644
--- a/modules/block/block.module
+++ b/modules/block/block.module
@@ -103,9 +103,9 @@ function block_admin_save($edit) {
 /**
  * update blocks db table with blocks currently exported by modules
  *
- * @param   array   $order_by   php array_multisort() style sort ordering, eg. "weight", SORT_ASC, SORT_STRING. see {@link http://www.php.net/manual/en/function.array-multisort.php}
- * @return  array   blocks currently exported by modules, sorted by $order_by
- * @access  private
+ * @param   $order_by   php <a href="http://www.php.net/manual/en/function.array-multisort.php">array_multisort()</a> style sort ordering, eg. "weight", SORT_ASC, SORT_STRING.
+ *
+ * @return  blocks currently exported by modules, sorted by $order_by
  */
 function _block_rehash($order_by = array("weight")) {
   $result = db_query("SELECT * FROM {blocks} ");
diff --git a/modules/search.module b/modules/search.module
index 9dedb035af4..3d4d191da84 100644
--- a/modules/search.module
+++ b/modules/search.module
@@ -64,7 +64,6 @@ function search_settings() {
 
 /**
  * search engine administration actions
- *
  */
 function search_admin() {
   $op = $_POST["op"];
@@ -90,8 +89,7 @@ function search_admin() {
 
 /**
  * perform a regularly run action across all modules that have the
- * <module>_update_index function in them.
- *
+ * <i>module</i>_update_index function in them.
  */
 function search_cron() {
   foreach (module_list() as $module) {
@@ -105,15 +103,16 @@ function search_cron() {
 }
 
 /**
- * Perform a search on a word(s)
+ * Perform a search on a word(s).
  *
- * Search function called by each node that supports the indexed search
+ * Search function called by each node that supports the indexed search.
  *
- * @param $search_array  an array as returned from <module>_search
- *                       of type array("keys" => ...,
- *                       "type" => ..., "select" => ...)
- *                       see node_search in node.module for an
- *                       explanation of array items
+ * @param $search_array  an array as returned from <i>module</i>_search
+ *   of type array("keys" => ..., "type" => ..., "select" => ...)
+ * @see   node_search for an explanation of array items
+ *
+ * @return  array of search results, each element being an array indexed with
+ *   "count", "title", "link", "user" (name), "date", "keywords"
  */
 function do_search($search_array) {
 
@@ -225,11 +224,9 @@ function do_search($search_array) {
 /**
  * Update the search_index table
  *
- * @param $search_array  an array as returned from <module>_update_index
- *                       of type array("last_update" => ...,
- *                       "node_type" => ..., "select" => ...)
- *                       see node_update_index in node.module for an
- *                       explanation of array items
+ * @param $search_array  an array as returned from <i>module</i>_update_index
+ *   of type array("last_update" => ..., "node_type" => ..., "select" => ...)
+ * @see   node_update_index for an explanation of array items
  */
 function update_index($search_array) {
   $last_update = variable_get($search_array["last_update"], 1);
diff --git a/modules/search/search.module b/modules/search/search.module
index 9dedb035af4..3d4d191da84 100644
--- a/modules/search/search.module
+++ b/modules/search/search.module
@@ -64,7 +64,6 @@ function search_settings() {
 
 /**
  * search engine administration actions
- *
  */
 function search_admin() {
   $op = $_POST["op"];
@@ -90,8 +89,7 @@ function search_admin() {
 
 /**
  * perform a regularly run action across all modules that have the
- * <module>_update_index function in them.
- *
+ * <i>module</i>_update_index function in them.
  */
 function search_cron() {
   foreach (module_list() as $module) {
@@ -105,15 +103,16 @@ function search_cron() {
 }
 
 /**
- * Perform a search on a word(s)
+ * Perform a search on a word(s).
  *
- * Search function called by each node that supports the indexed search
+ * Search function called by each node that supports the indexed search.
  *
- * @param $search_array  an array as returned from <module>_search
- *                       of type array("keys" => ...,
- *                       "type" => ..., "select" => ...)
- *                       see node_search in node.module for an
- *                       explanation of array items
+ * @param $search_array  an array as returned from <i>module</i>_search
+ *   of type array("keys" => ..., "type" => ..., "select" => ...)
+ * @see   node_search for an explanation of array items
+ *
+ * @return  array of search results, each element being an array indexed with
+ *   "count", "title", "link", "user" (name), "date", "keywords"
  */
 function do_search($search_array) {
 
@@ -225,11 +224,9 @@ function do_search($search_array) {
 /**
  * Update the search_index table
  *
- * @param $search_array  an array as returned from <module>_update_index
- *                       of type array("last_update" => ...,
- *                       "node_type" => ..., "select" => ...)
- *                       see node_update_index in node.module for an
- *                       explanation of array items
+ * @param $search_array  an array as returned from <i>module</i>_update_index
+ *   of type array("last_update" => ..., "node_type" => ..., "select" => ...)
+ * @see   node_update_index for an explanation of array items
  */
 function update_index($search_array) {
   $last_update = variable_get($search_array["last_update"], 1);
diff --git a/modules/taxonomy.module b/modules/taxonomy.module
index 135241f43c5..ca59cae258e 100644
--- a/modules/taxonomy.module
+++ b/modules/taxonomy.module
@@ -538,12 +538,12 @@ function _taxonomy_term_children($tid) {
 }
 
 /**
- * Try to map a string to existing vocabularies
+ * Try to map a string to existing vocabularies.
  * Provide case insensitive and trimmed map so as to
  * maximize likelihood of successful mapping.
  *
- * @param   string  $name  Name of the vocabulary to search
- * @return  array   array of matching vocabularies, as objects
+ * @param   $name  Name of the vocabulary to search
+ * @return  array of matching vocabularies, as objects
  */
 function taxonomy_get_vocabulary_by_name($name) {
   // LOWER is ANSI SQL-92
@@ -561,8 +561,8 @@ function taxonomy_get_vocabulary_by_name($name) {
  * Provide case insensitive and trimmed map so as to
  * maximize likelihood of successful mapping.
  *
- * @param   string  $name  Name of the term to search
- * @return  array   array of matching terms, as objects
+ * @param   name  Name of the term to search
+ * @return  rray of matching terms, as objects
  */
 function taxonomy_get_term_by_name($name) {
   // LOWER is ANSI SQL-92
diff --git a/modules/taxonomy/taxonomy.module b/modules/taxonomy/taxonomy.module
index 135241f43c5..ca59cae258e 100644
--- a/modules/taxonomy/taxonomy.module
+++ b/modules/taxonomy/taxonomy.module
@@ -538,12 +538,12 @@ function _taxonomy_term_children($tid) {
 }
 
 /**
- * Try to map a string to existing vocabularies
+ * Try to map a string to existing vocabularies.
  * Provide case insensitive and trimmed map so as to
  * maximize likelihood of successful mapping.
  *
- * @param   string  $name  Name of the vocabulary to search
- * @return  array   array of matching vocabularies, as objects
+ * @param   $name  Name of the vocabulary to search
+ * @return  array of matching vocabularies, as objects
  */
 function taxonomy_get_vocabulary_by_name($name) {
   // LOWER is ANSI SQL-92
@@ -561,8 +561,8 @@ function taxonomy_get_vocabulary_by_name($name) {
  * Provide case insensitive and trimmed map so as to
  * maximize likelihood of successful mapping.
  *
- * @param   string  $name  Name of the term to search
- * @return  array   array of matching terms, as objects
+ * @param   name  Name of the term to search
+ * @return  rray of matching terms, as objects
  */
 function taxonomy_get_term_by_name($name) {
   // LOWER is ANSI SQL-92