- Patch #10663 by JonBob: documentation improvements: fixed some typos and improved consistency to the use of Doxygen/api.module commands in the comments.

10 files changed, 88 insertions, 138 deletions

diff --git a/modules/aggregator.module b/modules/aggregator.module
index 65cfbf52a..57b98c50b 100644
--- a/modules/aggregator.module
+++ b/modules/aggregator.module
@@ -1019,12 +1019,11 @@ function aggregator_page_categories() {
 }
 
 /**
- * @addtogroup themeable
- * @{
+ * Format a news feed.
+ *
+ * @ingroup themeable
  */
-
 function theme_aggregator_feed($feed) {
-
   $output  = '';
 
   if ($feed->image) {
@@ -1048,6 +1047,11 @@ function theme_aggregator_feed($feed) {
   return $output;
 }
 
+/**
+ * Format an individual feed item for display in the block.
+ *
+ * @ingroup themeable
+ */
 function theme_aggregator_block_item($item, $feed = 0) {
   global $user;
 
@@ -1057,18 +1061,20 @@ function theme_aggregator_block_item($item, $feed = 0) {
     }
   }
 
-  // external link
+  // Display the external link to the item.
   $output .= "<a href=\"$item->link\">$item->title</a>\n";
 
   return $output;
 }
 
 /**
- * Returns a themed item heading for summary pages located at
- * aggregator/sources and aggregator/categories.
+ * Return a themed item heading for summary pages located at "aggregator/sources"
+ * and "aggregator/categories".
  *
  * @param $item The item object from the aggregator module.
  * @return A string containing the output.
+ *
+ * @ingroup themeable
  */
 function theme_aggregator_summary_item($item) {
   $output = '<a href="'. check_url($item->link) .'">'. $item->title .'</a> <span class="age">'. t('%age old', array('%age' => format_interval(time() - $item->timestamp))) .'</span>';
@@ -1078,6 +1084,11 @@ function theme_aggregator_summary_item($item) {
   return $output ."\n";
 }
 
+/**
+ * Format an individual feed item for display on the aggregator page.
+ *
+ * @ingroup themeable
+ */
 function theme_aggregator_page_item($item) {
   static $last;
 
@@ -1113,6 +1124,4 @@ function theme_aggregator_page_item($item) {
   return $output;
 }
 
-/** @} End of addtogroup themeable */
-
 ?>
diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module
index 65cfbf52a..57b98c50b 100644
--- a/modules/aggregator/aggregator.module
+++ b/modules/aggregator/aggregator.module
@@ -1019,12 +1019,11 @@ function aggregator_page_categories() {
 }
 
 /**
- * @addtogroup themeable
- * @{
+ * Format a news feed.
+ *
+ * @ingroup themeable
  */
-
 function theme_aggregator_feed($feed) {
-
   $output  = '';
 
   if ($feed->image) {
@@ -1048,6 +1047,11 @@ function theme_aggregator_feed($feed) {
   return $output;
 }
 
+/**
+ * Format an individual feed item for display in the block.
+ *
+ * @ingroup themeable
+ */
 function theme_aggregator_block_item($item, $feed = 0) {
   global $user;
 
@@ -1057,18 +1061,20 @@ function theme_aggregator_block_item($item, $feed = 0) {
     }
   }
 
-  // external link
+  // Display the external link to the item.
   $output .= "<a href=\"$item->link\">$item->title</a>\n";
 
   return $output;
 }
 
 /**
- * Returns a themed item heading for summary pages located at
- * aggregator/sources and aggregator/categories.
+ * Return a themed item heading for summary pages located at "aggregator/sources"
+ * and "aggregator/categories".
  *
  * @param $item The item object from the aggregator module.
  * @return A string containing the output.
+ *
+ * @ingroup themeable
  */
 function theme_aggregator_summary_item($item) {
   $output = '<a href="'. check_url($item->link) .'">'. $item->title .'</a> <span class="age">'. t('%age old', array('%age' => format_interval(time() - $item->timestamp))) .'</span>';
@@ -1078,6 +1084,11 @@ function theme_aggregator_summary_item($item) {
   return $output ."\n";
 }
 
+/**
+ * Format an individual feed item for display on the aggregator page.
+ *
+ * @ingroup themeable
+ */
 function theme_aggregator_page_item($item) {
   static $last;
 
@@ -1113,6 +1124,4 @@ function theme_aggregator_page_item($item) {
   return $output;
 }
 
-/** @} End of addtogroup themeable */
-
 ?>
diff --git a/modules/filter.module b/modules/filter.module
index 849c9ca4d..5c6931eed 100644
--- a/modules/filter.module
+++ b/modules/filter.module
@@ -558,11 +558,9 @@ function filter_list_format($format) {
 
 /**
  * @name Filtering functions
- *
+ * @{
  * Modules which need to have content filtered can use these functions to
  * interact with the filter system.
- *
- * @{
  */
 
 /**
@@ -666,7 +664,9 @@ function filter_access($format) {
     return isset($formats[$format]);
   }
 }
-/* @} */
+/**
+ * @} End of "Filtering functions".
+ */
 
 /**
  * Menu callback; show a page with long filter tips.
@@ -710,16 +710,9 @@ function _filter_tips($format, $long = false) {
 }
 
 /**
- * @addtogroup themeable
- * @{
- */
-
-/**
- * Format filter tips
+ * Format a set of filter tips.
  *
- * @param $tips
- * @param $long
- * @param $extra
+ * @ingroup themeable
  */
 function theme_filter_tips($tips, $long = false, $extra = '') {
   $output = '';
@@ -758,13 +751,10 @@ function theme_filter_tips($tips, $long = false, $extra = '') {
   return $output;
 }
 
-/** @} End of addtogroup themeable */
-
 /**
  * @name Standard filters
- *
- * Filters implemented by the filter.module.
  * @{
+ * Filters implemented by the filter.module.
  */
 
 /**
@@ -879,6 +869,8 @@ function _filter_autop($text) {
   return $text;
 }
 
-/* @} */
+/**
+ * @} End of "Standard filters".
+ */
 
 ?>
diff --git a/modules/filter/filter.module b/modules/filter/filter.module
index 849c9ca4d..5c6931eed 100644
--- a/modules/filter/filter.module
+++ b/modules/filter/filter.module
@@ -558,11 +558,9 @@ function filter_list_format($format) {
 
 /**
  * @name Filtering functions
- *
+ * @{
  * Modules which need to have content filtered can use these functions to
  * interact with the filter system.
- *
- * @{
  */
 
 /**
@@ -666,7 +664,9 @@ function filter_access($format) {
     return isset($formats[$format]);
   }
 }
-/* @} */
+/**
+ * @} End of "Filtering functions".
+ */
 
 /**
  * Menu callback; show a page with long filter tips.
@@ -710,16 +710,9 @@ function _filter_tips($format, $long = false) {
 }
 
 /**
- * @addtogroup themeable
- * @{
- */
-
-/**
- * Format filter tips
+ * Format a set of filter tips.
  *
- * @param $tips
- * @param $long
- * @param $extra
+ * @ingroup themeable
  */
 function theme_filter_tips($tips, $long = false, $extra = '') {
   $output = '';
@@ -758,13 +751,10 @@ function theme_filter_tips($tips, $long = false, $extra = '') {
   return $output;
 }
 
-/** @} End of addtogroup themeable */
-
 /**
  * @name Standard filters
- *
- * Filters implemented by the filter.module.
  * @{
+ * Filters implemented by the filter.module.
  */
 
 /**
@@ -879,6 +869,8 @@ function _filter_autop($text) {
   return $text;
 }
 
-/* @} */
+/**
+ * @} End of "Standard filters".
+ */
 
 ?>
diff --git a/modules/forum.module b/modules/forum.module
index 9be309d16..478827107 100644
--- a/modules/forum.module
+++ b/modules/forum.module
@@ -491,21 +491,9 @@ function forum_page($tid = 0, $display = 'all') {
 }
 
 /**
- * @addtogroup themeable
- * @{
- */
-
-/**
  * Format the forum body.
  *
- * @param forums
- * @param topics
- * @param parents
- * @param tid
- * @param sortby
- * @param forum_per_page
- *
- * @return the output for the forum body.
+ * @ingroup themeable
  */
 function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_per_page) {
   global $user;
@@ -575,11 +563,7 @@ function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_p
 /**
  * Format the forum listing.
  *
- * @param forums
- * @param parents
- * @param tid
- *
- * @return output for the forum listing.
+ * @ingroup themeable
  */
 function theme_forum_list($forums, $parents, $tid) {
   global $user;
@@ -632,12 +616,7 @@ function theme_forum_list($forums, $parents, $tid) {
 /**
  * Format the topic listing.
  *
- * @param tid
- * @param topics
- * @param sortby
- * @param forum_per_page
- *
- * @return output for the topic list.
+ * @ingroup themeable
  */
 function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) {
   global $forum_topic_list_header;
@@ -674,8 +653,6 @@ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) {
   return $output;
 }
 
-/** @} End of addtogroup themeable */
-
 function _forum_icon($new_posts, $num_posts = 0, $comment_mode = 0, $sticky = 0) {
 
   $base_path = variable_get('forum_icon_path', '');
diff --git a/modules/forum/forum.module b/modules/forum/forum.module
index 9be309d16..478827107 100644
--- a/modules/forum/forum.module
+++ b/modules/forum/forum.module
@@ -491,21 +491,9 @@ function forum_page($tid = 0, $display = 'all') {
 }
 
 /**
- * @addtogroup themeable
- * @{
- */
-
-/**
  * Format the forum body.
  *
- * @param forums
- * @param topics
- * @param parents
- * @param tid
- * @param sortby
- * @param forum_per_page
- *
- * @return the output for the forum body.
+ * @ingroup themeable
  */
 function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_per_page) {
   global $user;
@@ -575,11 +563,7 @@ function theme_forum_display($forums, $topics, $parents, $tid, $sortby, $forum_p
 /**
  * Format the forum listing.
  *
- * @param forums
- * @param parents
- * @param tid
- *
- * @return output for the forum listing.
+ * @ingroup themeable
  */
 function theme_forum_list($forums, $parents, $tid) {
   global $user;
@@ -632,12 +616,7 @@ function theme_forum_list($forums, $parents, $tid) {
 /**
  * Format the topic listing.
  *
- * @param tid
- * @param topics
- * @param sortby
- * @param forum_per_page
- *
- * @return output for the topic list.
+ * @ingroup themeable
  */
 function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) {
   global $forum_topic_list_header;
@@ -674,8 +653,6 @@ function theme_forum_topic_list($tid, $topics, $sortby, $forum_per_page) {
   return $output;
 }
 
-/** @} End of addtogroup themeable */
-
 function _forum_icon($new_posts, $num_posts = 0, $comment_mode = 0, $sticky = 0) {
 
   $base_path = variable_get('forum_icon_path', '');
diff --git a/modules/node.module b/modules/node.module
index 10cb1b3c9..d750593cb 100644
--- a/modules/node.module
+++ b/modules/node.module
@@ -65,13 +65,12 @@ function node_cron() {
 }
 
 /**
- * Menu callback; presents node-specific imformation from admin/help.
+ * Menu callback; presents node-specific imformation from "admin/help".
  */
 function node_help_page() {
   print theme('page', node_help('admin/help#node'));
 }
 
-
 /**
  * Gather a listing of links to nodes.
  *
@@ -131,7 +130,7 @@ function node_last_viewed($nid) {
 }
 
 /**
- * Determines whether the supplied timestamp is newer than the user's last view
+ * Determine whether the supplied timestamp is newer than the user's last view
  * of a given node.
  *
  * @param $nid
@@ -156,7 +155,7 @@ function node_is_new($nid, $timestamp) {
 }
 
 /**
- * Autogenerate a teaser for the given body text.
+ * Automatically generate a teaser for the given body text.
  */
 function node_teaser($body) {
 
@@ -235,7 +234,7 @@ function node_teaser($body) {
 
 
 /**
- * Determines the module that defines the node type of the given node.
+ * Determine the module that defines the node type of the given node.
  *
  * @param &$node
  *   Either a node object, a node array, or a string containing the node type.
@@ -273,7 +272,7 @@ function node_get_module_name($node) {
  * Get a list of all the defined node types.
  *
  * @return
- *   An list of all node types.
+ *   A list of all node types.
  */
 function node_list() {
   $types = array();
@@ -703,7 +702,7 @@ function node_admin_edit($node) {
 }
 
 /**
- * Generate the content administation overview.
+ * Generate the content administration overview.
  */
 function node_admin_nodes() {
   $filters = array(
@@ -835,7 +834,7 @@ function node_default_settings() {
 }
 
 /**
- * Generates an overview table of older revisions of a node.
+ * Generate an overview table of older revisions of a node.
  */
 function node_revision_overview($nid) {
   if (user_access('administer nodes')) {
@@ -1028,7 +1027,7 @@ function node_feed($nodes = 0, $channel = array()) {
 }
 
 /**
- * Preform validation checks on the given node.
+ * Perform validation checks on the given node.
  */
 function node_validate($node) {
   global $user;
@@ -1670,11 +1669,9 @@ function node_access_join_sql($node_alias = 'n', $node_access_alias = 'na') {
  */
 function node_access_where_sql($op = 'view', $node_access_alias = 'na') {
   if (user_access('administer nodes')) {
-    /**
-     * This number is being used in a SQL query in a boolean nature.
-     * It is "'1'" instead of "1" for database compatibility, as both
-     * Postgres and Mysql treat it as boolean in this case.
-     */
+    // This number is being used in a SQL query as a boolean.
+    // It is "'1'" instead of "1" for database compatibility, as both
+    // PostgreSQL and MySQL treat it as boolean in this case.
     return "'1'";
   }
 
@@ -1718,7 +1715,7 @@ function node_access_grants($op, $uid = NULL) {
 }
 
 /**
- * @} end of defgroup node_access
+ * @} End of "defgroup node_access".
  */
 
 ?>
diff --git a/modules/node/node.module b/modules/node/node.module
index 10cb1b3c9..d750593cb 100644
--- a/modules/node/node.module
+++ b/modules/node/node.module
@@ -65,13 +65,12 @@ function node_cron() {
 }
 
 /**
- * Menu callback; presents node-specific imformation from admin/help.
+ * Menu callback; presents node-specific imformation from "admin/help".
  */
 function node_help_page() {
   print theme('page', node_help('admin/help#node'));
 }
 
-
 /**
  * Gather a listing of links to nodes.
  *
@@ -131,7 +130,7 @@ function node_last_viewed($nid) {
 }
 
 /**
- * Determines whether the supplied timestamp is newer than the user's last view
+ * Determine whether the supplied timestamp is newer than the user's last view
  * of a given node.
  *
  * @param $nid
@@ -156,7 +155,7 @@ function node_is_new($nid, $timestamp) {
 }
 
 /**
- * Autogenerate a teaser for the given body text.
+ * Automatically generate a teaser for the given body text.
  */
 function node_teaser($body) {
 
@@ -235,7 +234,7 @@ function node_teaser($body) {
 
 
 /**
- * Determines the module that defines the node type of the given node.
+ * Determine the module that defines the node type of the given node.
  *
  * @param &$node
  *   Either a node object, a node array, or a string containing the node type.
@@ -273,7 +272,7 @@ function node_get_module_name($node) {
  * Get a list of all the defined node types.
  *
  * @return
- *   An list of all node types.
+ *   A list of all node types.
  */
 function node_list() {
   $types = array();
@@ -703,7 +702,7 @@ function node_admin_edit($node) {
 }
 
 /**
- * Generate the content administation overview.
+ * Generate the content administration overview.
  */
 function node_admin_nodes() {
   $filters = array(
@@ -835,7 +834,7 @@ function node_default_settings() {
 }
 
 /**
- * Generates an overview table of older revisions of a node.
+ * Generate an overview table of older revisions of a node.
  */
 function node_revision_overview($nid) {
   if (user_access('administer nodes')) {
@@ -1028,7 +1027,7 @@ function node_feed($nodes = 0, $channel = array()) {
 }
 
 /**
- * Preform validation checks on the given node.
+ * Perform validation checks on the given node.
  */
 function node_validate($node) {
   global $user;
@@ -1670,11 +1669,9 @@ function node_access_join_sql($node_alias = 'n', $node_access_alias = 'na') {
  */
 function node_access_where_sql($op = 'view', $node_access_alias = 'na') {
   if (user_access('administer nodes')) {
-    /**
-     * This number is being used in a SQL query in a boolean nature.
-     * It is "'1'" instead of "1" for database compatibility, as both
-     * Postgres and Mysql treat it as boolean in this case.
-     */
+    // This number is being used in a SQL query as a boolean.
+    // It is "'1'" instead of "1" for database compatibility, as both
+    // PostgreSQL and MySQL treat it as boolean in this case.
     return "'1'";
   }
 
@@ -1718,7 +1715,7 @@ function node_access_grants($op, $uid = NULL) {
 }
 
 /**
- * @} end of defgroup node_access
+ * @} End of "defgroup node_access".
  */
 
 ?>
diff --git a/modules/search.module b/modules/search.module
index 4143cfda2..f42c1e2ba 100644
--- a/modules/search.module
+++ b/modules/search.module
@@ -246,7 +246,7 @@ function update_index($search_array) {
 
       // Trash any existing entries in the search index for this node,
       // in case it is a modified node.
-      db_query("DELETE from {search_index} where lno = '". $node['lno'] ."' and type = '". $node_type ."'");
+      db_query("DELETE from {search_index} WHERE lno = '". $node['lno'] ."' AND type = '". $node_type ."'");
 
       // Build the word list (teaser not included, as it would give a
       // false count of the number of hits).
diff --git a/modules/search/search.module b/modules/search/search.module
index 4143cfda2..f42c1e2ba 100644
--- a/modules/search/search.module
+++ b/modules/search/search.module
@@ -246,7 +246,7 @@ function update_index($search_array) {
 
       // Trash any existing entries in the search index for this node,
       // in case it is a modified node.
-      db_query("DELETE from {search_index} where lno = '". $node['lno'] ."' and type = '". $node_type ."'");
+      db_query("DELETE from {search_index} WHERE lno = '". $node['lno'] ."' AND type = '". $node_type ."'");
 
       // Build the word list (teaser not included, as it would give a
       // false count of the number of hits).