- #9287: More doxygen/documentation fixes by JonBob

7 files changed, 493 insertions, 308 deletions

diff --git a/includes/bootstrap.inc b/includes/bootstrap.inc
index 77821e41f..905612bf6 100644
--- a/includes/bootstrap.inc
+++ b/includes/bootstrap.inc
@@ -3,7 +3,6 @@
 
 /**
  * @file
- *
  * Functions that need to be loaded on every Drupal request.
  */
 
diff --git a/includes/common.inc b/includes/common.inc
index 2c8ce54b1..4ea42b449 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -3,7 +3,6 @@
 
 /**
  * @file
- *
  * Common functions that many Drupal modules will need to reference.
  *
  * The functions that are critical and need to be available even when serving
@@ -760,7 +759,10 @@ function search_type($type, $action = NULL, $keys = NULL, $options = NULL) {
 
   return search_form($action, $keys, $options) . '<br />'. search_data($keys);
 }
-/* @} */
+
+/**
+ * @} end of defgroup search
+ */
 
 function check_form($text) {
   return drupal_specialchars($text, ENT_QUOTES);
@@ -1004,6 +1006,8 @@ function format_name($object) {
 /**
  * @defgroup form Form generation
  * @{
+ *
+ *
  */
 
 /**
@@ -1446,7 +1450,10 @@ function form_weight($title = NULL, $name = 'weight', $value = 0, $delta = 10, $
 
   return form_select($title, $name, $value, $weights, $description, $extra);
 }
-/* @} */
+
+/**
+ * @} end of defgroup form
+ */
 
 /**
  * Generate an internal Drupal URL.
diff --git a/includes/menu.inc b/includes/menu.inc
index 84f855a57..c3ca98fd1 100644
--- a/includes/menu.inc
+++ b/includes/menu.inc
@@ -2,6 +2,11 @@
 /* $Id$ */
 
 /**
+ * @file
+ * API for the Drupal menu system.
+ */
+
+/**
  * @defgroup menu Menu system
  * @{
  *
@@ -493,7 +498,9 @@ function menu_rebuild() {
   _menu_build();
 }
 
-/** @} end of "menu" function group */
+/**
+ * @} end of defgroup menu
+ */
 
 /**
  * @addtogroup themeable
@@ -591,7 +598,9 @@ function theme_menu_local_task($mid, $active) {
   }
 }
 
-/** @} End of addtogroup themeable */
+/**
+ * @} end of addtogroup themeable
+ */
 
 /**
  * Returns an array with the menu items that lead to the current menu item.
diff --git a/includes/module.inc b/includes/module.inc
index 496aa01f6..567dedd8e 100644
--- a/includes/module.inc
+++ b/includes/module.inc
@@ -2,6 +2,11 @@
 // $Id$
 
 /**
+ * @file
+ * API for loading and interacting with Drupal modules.
+ */
+
+/**
  * Initialize all modules.
  *
  * To change the required set of modules, change this function as well as
diff --git a/includes/pager.inc b/includes/pager.inc
index 837f8e2fa..01a7924a6 100644
--- a/includes/pager.inc
+++ b/includes/pager.inc
@@ -2,62 +2,64 @@
 // $Id$
 
 /**
- * @defgroup pager Pager interface
- * @{
- *
- * Pager external functions (API).
+ * @file
+ * Functions to aid in presenting database results as a set of pages.
  */
 
 /**
+ * Perform a paged database query.
+ * @ingroup database
+ *
  * 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 sticky DESC, created DESC" to read
- * "SELECT COUNT(*) FROM node WHERE status = '1' ORDER BY sticky DESC, created
- * DESC". Rewriting the query is accomplished using a regular expression.
+ * by the query to compute the number of pages (the number of records / records
+ * per page). This is done by inserting "COUNT(*)" in the original query. For
+ * example, the query "SELECT nid, type FROM node WHERE status = '1' ORDER BY
+ * sticky DESC, created DESC" would be rewritten to read "SELECT COUNT(*) FROM
+ * node WHERE status = '1' ORDER BY sticky 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
+ * 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
+ * For example, if you want to page the query "SELECT COUNT(*), TYPE FROM node
+ * GROUP BY TYPE", pager_query() would invoke the incorrect query "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 distinguish 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
+ * @param $query
+ *   The SQL query that needs paging.
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $count_query
+ *   An SQL query used to count matching records.
+ * @return
+ *   A database query result resource, or FALSE if the query was not executed
+ *   correctly.
  */
-function pager_query($query, $limit = 10, $element = 0, $count_query = "") {
+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/is", "/ORDER BY .*/"), array("SELECT COUNT(*) FROM", ""), $query)));
+  $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/is', '/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);
+  // 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 defgroup pager_api */
 
 /**
  * @addtogroup themeable
@@ -65,26 +67,42 @@ function pager_query($query, $limit = 10, $element = 0, $count_query = "") {
  */
 
 /**
- * When writing themes, you can rewrite this pager function in your theme.
- * You need to call theme("pager", ...) to get a pager.
+ * Format a query pager.
+ *
+ * Menu callbacks that display paged query results should call theme('pager') to
+ * retrieve a pager control so that users can view other results.
+ *
+ * @param $tags
+ *   An array of labels for the controls in the pager.
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager links.
+ * @return
+ *   An HTML string that generates the query pager.
  */
-function theme_pager($tags = "", $limit = 10, $element = 0, $attributes = array()) {
+function theme_pager($tags = array(), $limit = 10, $element = 0, $attributes = array()) {
   global $pager_total;
   $output = '';
 
   if ($pager_total[$element] > $limit) {
-    $output .= "<div id=\"pager\" class=\"container-inline\">";
-    $output .= "<div>". pager_first(($tags[0] ? $tags[0] : t("first page")), $limit, $element, $attributes) ."</div>";
-    $output .= "<div>". pager_previous(($tags[1] ? $tags[1] : t("previous page")), $limit, $element, 1, $attributes) ."</div>";
-    $output .= "<div>". pager_list($limit, $element, ($tags[2] ? $tags[2] : 9 ), "", $attributes) ."</div>";
-    $output .= "<div>". pager_next(($tags[3] ? $tags[3] : t("next page")), $limit, $element, 1, $attributes) ."</div>";
-    $output .= "<div>". pager_last(($tags[4] ? $tags[4] : t("last page")), $limit, $element, $attributes) ."</div>";
-    $output .= "</div>";
+    $output .= '<div id="pager" class="container-inline">';
+    $output .= '<div>'. pager_first(($tags[0] ? $tags[0] : t('first page')), $limit, $element, $attributes) .'</div>';
+    $output .= '<div>'. pager_previous(($tags[1] ? $tags[1] : t('previous page')), $limit, $element, 1, $attributes) .'</div>';
+    $output .= '<div>'. pager_list($limit, $element, ($tags[2] ? $tags[2] : 9 ), '', $attributes) .'</div>';
+    $output .= '<div>'. pager_next(($tags[3] ? $tags[3] : t('next page')), $limit, $element, 1, $attributes) .'</div>';
+    $output .= '<div>'. pager_last(($tags[4] ? $tags[4] : t('last page')), $limit, $element, $attributes) .'</div>';
+    $output .= '</div>';
 
     return $output;
   }
 }
-/** @} End of addtogroup themeable */
+
+/**
+ * @} end of addtogroup themeable
+ */
 
 /**
  * @name Pager pieces
@@ -94,80 +112,94 @@ function theme_pager($tags = "", $limit = 10, $element = 0, $attributes = array(
  */
 
 /**
- * displays a "first-page" link
+ * Format a "first page" link.
  *
- * @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
+ * @param $text
+ *   The name (or image) of the link.
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager links.
+ * @return
+ *   An HTML string that generates this piece of the query pager.
  */
 function pager_first($text, $limit, $element = 0, $attributes = array()) {
   global $pager_from_array;
 
   if ($pager_from_array[$element]) {
-    return "<a href=\"". pager_link(pager_load_array(0, $element, $pager_from_array), $element, $attributes) ."\">$text</a>";
+    return '<a href="'. pager_link(pager_load_array(0, $element, $pager_from_array), $element, $attributes) .'">'. $text .'</a>';
   }
   else {
-    // we are already at the first page, return nothing
-    return " ";
+    // We are already at the first page, so return nothing.
+    return ' ';
   }
 }
 
 /**
- * displays a "previous-page" link
- *
- * @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.)
+ * Format a "previous page" link.
  *
- * @return string html of this pager piece
+ * @param $text
+ *   The name (or image) of the link.
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $interval
+ *   The number of pages to move backward when the link is clicked.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager links.
+ * @return
+ *   An HTML string that generates this piece of the query pager.
  */
-function pager_previous($text, $limit, $element = 0, $n = 1, $attributes = array()) {
+function pager_previous($text, $limit, $element = 0, $interval = 1, $attributes = array()) {
   global $pager_from_array;
-  $from_new = pager_load_array(((int)$pager_from_array[$element] - ((int)$limit * (int)$n)), $element, $pager_from_array);
+  $from_new = pager_load_array(((int)$pager_from_array[$element] - ((int)$limit * (int)$interval)), $element, $pager_from_array);
   if ($from_new[$element] < 1) {
     return pager_first($text, $limit, $element, $attributes);
   }
-  return "<a href=\"". pager_link($from_new, $element, $attributes) ."\">$text</a>";
+  return '<a href="'. pager_link($from_new, $element, $attributes) .'">'. $text .'</a>';
 }
 
 /**
- * displays a "next-page" link
- *
- * @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.)
+ * Format a "next page" link.
  *
- * @return string html of this pager piece
+ * @param $text
+ *   The name (or image) of the link.
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $interval
+ *   The number of pages to move forward when the link is clicked.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager links.
+ * @return
+ *   An HTML string that generates this piece of the query pager.
  */
-function pager_next($text, $limit, $element = 0, $n = 1, $attributes = array()) {
+function pager_next($text, $limit, $element = 0, $interval = 1, $attributes = array()) {
   global $pager_from_array, $pager_total;
-  $from_new = pager_load_array(((int)$pager_from_array[$element] + ((int)$limit * (int)$n)), $element, $pager_from_array);
+  $from_new = pager_load_array(((int)$pager_from_array[$element] + ((int)$limit * (int)$interval)), $element, $pager_from_array);
   if ($from_new[$element] < $pager_total[$element]) {
-    return "<a href=\"". pager_link($from_new, $element, $attributes) ."\">$text</a>";
+    return '<a href="'. pager_link($from_new, $element, $attributes) .'">'. $text .'</a>';
   }
-  return " ";
+  return ' ';
 }
 
 /**
- * displays a "last-page" link
+ * Format a "last page" link.
  *
- * @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
+ * @param $text
+ *   The name (or image) of the link.
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager links.
+ * @return
+ *   An HTML string that generates this piece of the query pager.
  */
 function pager_last($text, $limit, $element = 0, $attributes = array()) {
   global $pager_from_array, $pager_total;
@@ -177,22 +209,26 @@ function pager_last($text, $limit, $element = 0, $attributes = array()) {
     return pager_next($text, $limit, $element, 1, $attributes);
   }
   if (($from_new[$element] > $pager_from_array[$element]) && ($from_new[$element] > 0) && $from_new[$element] < $pager_total[$element]) {
-    return "<a href=\"". pager_link($from_new, $element, $attributes) ."\">$text</a>";
+    return '<a href="'. pager_link($from_new, $element, $attributes) .'">'. $text .'</a>';
   }
-  return " ";
+  return ' ';
 }
 
 /**
- * displays "%d through %d of $d" type detail about the cur page
- *
- * @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
+ * Format a summary of the current pager position, such as "6 through 10 of 52".
  *
- * @return string html of this pager piece
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $format
+ *   A printf-style format string for customizing the pager text.
+ * @return
+ *   An HTML string that generates this piece of the query pager.
  */
-function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") {
+function pager_detail($limit, $element = 0, $format = '%d through %d of %d.') {
   global $pager_from_array, $pager_total;
+  $output = '';
 
   if ($pager_total[$element] > (int)$pager_from_array[$element] + 1) {
     $output = sprintf($format, (int)$pager_from_array[$element] + 1, ((int)$pager_from_array[$element] + $limit <= $pager_total[$element] ? (int)$pager_from_array[$element] + $limit : $pager_total[$element]), $pager_total[$element]);
@@ -202,22 +238,26 @@ function pager_detail($limit, $element = 0, $format = "%d through %d of %d.") {
 }
 
 /**
- * displays a list of nearby pages with additional nodes
- *
- * @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.)
+ * Format a list of nearby pages with additional query results.
  *
- * @return string html of this pager piece
+ * @param $limit
+ *   The number of query results to display per page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $quantity
+ *   The number of pages in the list.
+ * @param $text
+ *   A string of text to display before the page list.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager links.
+ * @return
+ *   An HTML string that generates this piece of the query pager.
  */
-function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes = array()) {
+function pager_list($limit, $element = 0, $quantity = 5, $text = '', $attributes = array()) {
   global $pager_from_array, $pager_total;
 
-  // calculate various markers within this pager piece:
-  // middle used to "center" pages around current page
+  // Calculate various markers within this pager piece:
+  // Middle is used to "center" pages around the current page.
   $pager_middle = ceil((int)$quantity / 2);
   // offset adds "offset" second page
   $pager_offset = (int)$pager_from_array[$element] % (int)$limit;
@@ -238,36 +278,36 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes
     $pager_max++;
     $pager_current++;
   }
-// end of various marker calculations
+// End of marker calculations.
 
-// prepare for generation loop
+// Prepare for generation loop.
   $i = (int)$pager_first;
   if ($pager_last > $pager_max) {
-    // adjust "center" if at end of query
+    // Adjust "center" if at end of query.
     $i = $i + (int)($pager_max - $pager_last);
     $pager_last = $pager_max;
   }
   if ($i <= 0) {
-    // adjust "center" if at start of query
+    // Adjust "center" if at start of query.
     $pager_last = $pager_last + (1 - $i);
     $i = 1;
   }
-// end of generation loop preparation
+// End of generation loop preparation.
 
-  // when there is more than one page, create the pager list
+  // When there is more than one page, create the pager list.
   if ($i != $pager_max) {
-    $output = "$text";
+    $output = $text;
     if ($i > 1) {
-      $output .= "... ";
+      $output .= '... ';
     }
 
-    // finally we're ready to generate the actual pager piece
+    // Now generate the actual pager piece.
     for (; $i <= $pager_last && $i <= $pager_max; $i++) {
       if ($i < $pager_current) {
         $output .= pager_previous($i, $limit, $element, ($pager_current - $i), $attributes) ." ";
       }
       if ($i == $pager_current) {
-        $output .= "<strong>$i</strong> ";
+        $output .= '<strong>'. $i .'</strong> ';
       }
       if ($i > $pager_current) {
         $output .= pager_next($i, $limit, $element, ($i - $pager_current), $attributes) ." ";
@@ -275,7 +315,7 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes
     }
 
     if ($i < $pager_max) {
-      $output .= "...";
+      $output .= '...';
     }
   }
 
@@ -283,20 +323,32 @@ function pager_list($limit, $element = 0, $quantity = 5, $text = "", $attributes
 }
 /* @} End of member group pager pieces */
 
+/**
+ * Format a link to a specific query result page.
+ *
+ * @param $from_new
+ *   The first result to display on the linked page.
+ * @param $element
+ *   An optional integer to distinguish between multiple pagers on one page.
+ * @param $attributes
+ *   An associative array of query string parameters to append to the pager link.
+ * @return
+ *   An HTML string that generates the link.
+ */
 function pager_link($from_new, $element, $attributes = array()) {
   $q = $_GET['q'];
   $from = array_key_exists('from', $_GET) ? $_GET['from'] : '';
 
   foreach($attributes as $key => $value) {
-    $query[] = "$key=$value";
+    $query[] = $key .'='. $value;
   }
 
-  $from_new = pager_load_array($from_new[$element], $element, explode("," ,$from));
+  $from_new = pager_load_array($from_new[$element], $element, explode(',', $from));
   if (count($attributes)) {
-    $url = url($q, "from=". implode($from_new, ",") ."&amp;". implode("&amp;", $query));
+    $url = url($q, 'from='. implode($from_new, ',') .'&amp;'. implode('&amp;', $query));
   }
   else {
-    $url = url($q, "from=". implode($from_new, ","));
+    $url = url($q, 'from='. implode($from_new, ','));
   }
 
   return $url;
diff --git a/includes/tablesort.inc b/includes/tablesort.inc
index e72e078f5..7a3fcf1ee 100644
--- a/includes/tablesort.inc
+++ b/includes/tablesort.inc
@@ -1,6 +1,17 @@
 <?php
 // $Id$
 
+/**
+ * @file
+ * Functions to aid in the creation of sortable tables.
+ *
+ * All tables created with a call to theme('table') have the option of having
+ * column headers that the user can click on to sort the table by that column.
+ */
+
+/**
+ * Initialize the table sort context.
+ */
 function tablesort_init($header) {
   $ts = tablesort_get_order($header);
   $ts['sort'] = tablesort_get_sort($header);
@@ -8,13 +19,35 @@ function tablesort_init($header) {
   return $ts;
 }
 
+/**
+ * Fetch pager link arguments.
+ *
+ * When producing a sortable table that presents paged data, pass the output
+ * of this function into theme('pager') to preserve the current sort order.
+ */
 function tablesort_pager() {
   $cgi = $_SERVER['REQUEST_METHOD'] == 'GET' ? $_GET : $_POST;
   unset($cgi['q'], $cgi['from']);
   return $cgi;
 }
 
-function tablesort_sql($header, $before = "") {
+/**
+ * Create an SQL sort clause.
+ * @ingroup database
+ *
+ * This function produces the ORDER BY clause to insert in your SQL queries,
+ * assuring that the returned database table rows match the sort order chosen
+ * by the user.
+ *
+ * @param $header
+ *   An array of column headers in the format described in theme_table().
+ * @param $before
+ *   An SQL string to insert after ORDER BY and before the table sorting code.
+ *   Useful for sorting by important attributes like "sticky" first.
+ * @return
+ *   An SQL string to append to the end of a query.
+ */
+function tablesort_sql($header, $before = '') {
   $ts = tablesort_init($header);
   if ($ts['sql']) {
     $sql = check_query($ts['sql']);
@@ -23,8 +56,23 @@ function tablesort_sql($header, $before = "") {
   }
 }
 
+/**
+ * Format a column header.
+ *
+ * If the cell in question is the column header for the current sort criterion,
+ * it gets special formatting. All possible sort criteria become links.
+ *
+ * @param $cell
+ *   The cell to format.
+ * @param $header
+ *   An array of column headers in the format described in theme_table().
+ * @param $ts
+ *   The current table sort context as returned from tablesort_init().
+ * @return
+ *   A properly formatted cell, ready for _theme_table_cell().
+ */
 function tablesort_header($cell, $header, $ts) {
-  // special formatting for the currently sorted column header
+  // Special formatting for the currently sorted column header.
   if (is_array($cell) && $cell['field']) {
     if ($cell['data'] == $ts['name']) {
       $ts['sort'] = (($ts['sort'] == 'asc') ? 'desc' : 'asc');
@@ -37,13 +85,29 @@ function tablesort_header($cell, $header, $ts) {
       $ts['sort'] = 'asc';
     }
     $title = t('sort by %s', array('%s' => $cell['data']));
-    $cell['data'] = l($cell['data'] . $image, $_GET['q'], array('title' => $title), "sort=". $ts['sort']. "&amp;order=". urlencode($cell['data']). $ts['query_string']);
+    $cell['data'] = l($cell['data'] . $image, $_GET['q'], array('title' => $title), 'sort="'. $ts['sort'] .'&amp;order='. urlencode($cell['data']). $ts['query_string']);
 
     unset($cell['field'], $cell['sort']);
   }
   return $cell;
 }
 
+/**
+ * Format a table cell.
+ *
+ * Adds a class attribute to all cells in the currently active column.
+ *
+ * @param $cell
+ *   The cell to format.
+ * @param $header
+ *   An array of column headers in the format described in theme_table().
+ * @param $ts
+ *   The current table sort context as returned from tablesort_init().
+ * @param $i
+ *   The index of the cell's table column.
+ * @return
+ *   A properly formatted cell, ready for _theme_table_cell().
+ */
 function tablesort_cell($cell, $header, $ts, $i) {
   if ($header[$i]['data'] == $ts['name'] && $header[$i]['field']) {
     if (is_array($cell)) {
@@ -56,6 +120,13 @@ function tablesort_cell($cell, $header, $ts, $i) {
   return $cell;
 }
 
+/**
+ * Compose a query string to append to table sorting requests.
+ *
+ * @return
+ *   A query string that consists of all components of the current page request
+ *   except for those pertaining to table sorting.
+ */
 function tablesort_get_querystring() {
   $cgi = $_SERVER['REQUEST_METHOD'] == 'GET' ? $_GET : $_POST;
   foreach ($cgi as $key => $val) {
@@ -66,6 +137,16 @@ function tablesort_get_querystring() {
   return $query_string;
 }
 
+/**
+ * Determine the current sort criterion.
+ *
+ * @param $headers
+ *   An array of column headers in the format described in theme_table().
+ * @return
+ *   An associative array describing the criterion, containing the keys:
+ *   - "name": The localized title of the table column.
+ *   - "sql": The name of the database field to sort on.
+ */
 function tablesort_get_order($headers) {
   $order = $_GET['order'];
   foreach ($headers as $header) {
@@ -93,14 +174,22 @@ function tablesort_get_order($headers) {
   }
 }
 
+/**
+ * Determine the current sort direction.
+ *
+ * @param $headers
+ *   An array of column headers in the format described in theme_table().
+ * @return
+ *   The current sort direction ("asc" or "desc").
+ */
 function tablesort_get_sort($headers) {
   if ($_GET['sort']) {
     return ($_GET['sort'] == 'desc') ? 'desc' : 'asc';
   }
-  // user has not specified a sort.  check module for default and if none, use 'asc'
+  // User has not specified a sort. Use default if specified; otherwise use "asc".
   else {
     foreach ($headers as $header) {
-      if (is_array($header) && isset($header['sort'])) {
+      if (is_array($header) && array_key_exists('sort', $header)) {
         return $header['sort'];
       }
     }
diff --git a/includes/theme.inc b/includes/theme.inc
index efc35721d..c43b45df6 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -3,8 +3,7 @@
 
 /**
  * @file
- *
- * Theme System - controls the output of Drupal.
+ * The theme system, which controls the output of Drupal.
  *
  * The theme system allows for nearly all output of the Drupal system to be
  * customized by user themes.
@@ -21,32 +20,26 @@
  * @return a string containing the help output.
  */
 function theme_help($section) {
-  $output = '';
-
   switch ($section) {
     case 'admin/themes#description':
-      $output = t("The base theme");
-      break;
+      return t('The base theme');
   }
-  return $output;
 }
 
 /**
  * Initialize the theme system by loading the theme.
  *
- * @return the name of the currently selected theme.
+ * @return
+ *   The name of the currently selected theme.
  */
 function init_theme() {
   global $user;
 
   $themes = list_themes();
 
-  /*
-  ** Only select the user selected theme if it is available in the
-  ** list of enabled themes.
-  */
-
-  $theme = $user->theme && $themes[$user->theme] ? $user->theme : variable_get("theme_default", 0);
+  // Only select the user selected theme if it is available in the
+  // list of enabled themes.
+  $theme = $user->theme && $themes[$user->theme] ? $user->theme : variable_get('theme_default', 0);
 
   include_once($themes[$theme]->filename);
 
@@ -57,10 +50,11 @@ function init_theme() {
  * Provides a list of currently available themes.
  *
  * @param $refresh
- *
- * @return an array of the currently available themes.
+ *   Whether to reload the list of themes from the database.
+ * @return
+ *   An array of the currently available themes.
  */
-function list_themes($refresh = 0) {
+function list_themes($refresh = FALSE) {
   static $list;
 
   if ($refresh) {
@@ -81,14 +75,22 @@ function list_themes($refresh = 0) {
 }
 
 /**
- * External interface of the theme system to all other modules, and core files.
+ * Generate the themed representation of a Drupal object.
  *
  * 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
+ * is called.
+ *
+ * For example, to retrieve the HTML that is output by theme_page($output), a
+ * module should call theme('page', $output).
  *
- * @return themed output.
+ * @param $function
+ *   The name of the theme function to call.
+ * @param ...
+ *   Additional arguments to pass along to the theme function.
+ * @return
+ *   An HTML string that generates the themed output.
  */
 function theme() {
   global $theme;
@@ -96,18 +98,16 @@ function theme() {
   $args = func_get_args();
   $function = array_shift($args);
 
-  if (($theme != '') && (function_exists($theme ."_". $function))) {
-    return call_user_func_array($theme ."_". $function, $args);
+  if (($theme != '') && (function_exists($theme .'_'. $function))) {
+    return call_user_func_array($theme .'_'. $function, $args);
   }
-  elseif (function_exists("theme_". $function)){
-    return call_user_func_array("theme_". $function, $args);
+  elseif (function_exists('theme_'. $function)){
+    return call_user_func_array('theme_'. $function, $args);
   }
 }
 
 /**
- * Returns the path to the currently selected theme.
- *
- * @return the path to the the currently selected theme.
+ * Return the path to the currently selected theme.
  */
 function path_to_theme() {
   global $theme;
@@ -121,22 +121,26 @@ function path_to_theme() {
  * @defgroup themeable Themeable functions
  * @{
  *
- * Themeable functions - functions that can be styled differently in themes.
+ * All functions that produce HTML for display should be themeable. This means
+ * that they should be named with the theme_ prefix, and invoked using theme()
+ * rather than being called directly. This allows themes to override the display
+ * of any Drupal object.
  *
- * @see theme
  * @see theme.inc
  */
 
 /**
- * Returns an entire Drupal page displaying the supplied content.
- *
- * @param $content a string containing the content to display
- * @param $title (optional) page title (\<head>\<title>)
- * @param $breadcrumb (optional) page breadcrumb
- *
- * @see drupal_breadcrumb
- *
- * @return a string containing the @a page output.
+ * Return an entire Drupal page displaying the supplied content.
+ *
+ * @param $content
+ *   A string to display in the main content area of the page.
+ * @param $title
+ *   The title of the page, if different from that provided by the menu system.
+ * @param $breadcrumb
+ *   The breadcrumb trail for the page, if different from that provided by the
+ *   menu system. Use menu_set_location() instead, if possible.
+ * @return
+ *   A string containing the entire HTML page.
  */
 function theme_page($content, $title = NULL, $breadcrumb = NULL) {
   if (isset($title)) {
@@ -148,28 +152,28 @@ function theme_page($content, $title = NULL, $breadcrumb = NULL) {
   }
 
   $output = "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n";
-  $output .= "<html xmlns=\"http://www.w3.org/1999/xhtml\">";
-  $output .= "<head>";
-  $output .= " <title>". (drupal_get_title() ? drupal_get_title() : variable_get('site_name', "drupal")) ."</title>";
+  $output .= '<html xmlns="http://www.w3.org/1999/xhtml">';
+  $output .= '<head>';
+  $output .= ' <title>'. (drupal_get_title() ? drupal_get_title() : variable_get('site_name', 'drupal')) .'</title>';
   $output .= drupal_get_html_head();
 
-  $output .= " </head>";
-  $output .= " <body style=\"background-color: #fff; color: #000;\"". theme("onload_attribute"). "\">";
-  $output .= "<table border=\"0\" cellspacing=\"4\" cellpadding=\"4\"><tr><td style=\"vertical-align: top; width: 170px;\">";
+  $output .= ' </head>';
+  $output .= ' <body style="background-color: #fff; color: #000;"'. theme('onload_attribute'). '">';
+  $output .= '<table border="0" cellspacing="4" cellpadding="4"><tr><td style="vertical-align: top; width: 170px;">';
 
-  $output .= theme("box", t("Navigation"), @implode("<br />", link_page()));
-  $output .= theme("blocks", "all");
-  $output .= "</td><td style=\"vertical-align: top;\">";
+  $output .= theme('box', t('Navigation'), @implode('<br />', link_page()));
+  $output .= theme('blocks', 'all');
+  $output .= '</td><td style="vertical-align: top;">';
 
-  $output .= theme("breadcrumb", drupal_get_breadcrumb());
-  $output .= "<h1>" . drupal_get_title() . "</h1>";
+  $output .= theme('breadcrumb', drupal_get_breadcrumb());
+  $output .= '<h1>' . drupal_get_title() . '</h1>';
 
   if ($tabs = theme('menu_local_tasks')) {
    $output .= $tabs;
   }
 
   if ($help = menu_get_active_help()) {
-    $output .= "<small>$help</small><hr />";
+    $output .= '<small>'. $help .'</small><hr />';
   }
 
   $output .= theme_status_messages();
@@ -178,9 +182,9 @@ function theme_page($content, $title = NULL, $breadcrumb = NULL) {
   $output .= $content;
   $output .= "\n<!-- end content -->\n";
 
-  $output .= "</td></tr></table>";
+  $output .= '</td></tr></table>';
   $output .= theme_closure();
-  $output .= "</body></html>";
+  $output .= '</body></html>';
 
   return $output;
 }
@@ -189,7 +193,8 @@ function theme_page($content, $title = NULL, $breadcrumb = NULL) {
  * Returns themed set of status and/or error messages.  The messages are grouped
  * by type.
  *
- * @return a string containing the messages.
+ * @return
+ *   A string containing the messages.
  */
 function theme_status_messages() {
   if ($data = drupal_get_messages()) {
@@ -199,7 +204,7 @@ function theme_status_messages() {
       if (count($messages) > 1) {
         $output .= " <ul>\n";
         foreach($messages as $message) {
-          $output .= "  <li>". ucfirst($message) ."</li>\n";
+          $output .= '  <li>'. ucfirst($message) ."</li>\n";
         }
         $output .= " </ul>\n";
       }
@@ -213,94 +218,97 @@ function theme_status_messages() {
   }
 }
 
-
 /**
- * Returns themed set of links.
- *
- * @param $links an array of @a links to be themed.
- * @param $delimiter (optional) @a delimiter used to separate the links.
- *
- * @return a string containing the @a links output.
+ * Return a themed set of links.
+ *
+ * @param $links
+ *   An array of links to be themed.
+ * @param $delimiter
+ *   A string used to separate the links.
+ * @return
+ *   A string containing the themed links.
  */
-function theme_links($links, $delimiter = " | ") {
+function theme_links($links, $delimiter = ' | ') {
   return implode($delimiter, $links);
 }
 
 /**
- * Returns themed image.
- *
- * @param $name the @a name of the image file.
+ * Return a themed image.
  *
- * @return a string containing the @a image output.
+ * @param $name
+ *   The name of the image file.
+ * @return
+ *   The pathname of the themed image.
  */
 function theme_image($name) {
-  return "misc/$name";
+  return 'misc/'. $name;
 }
 
 /**
- * Returns a themed breadcrumb menu.
+ * Return a themed breadcrumb trail.
  *
- * @param $breadcrumb an array containing the breadcrumb links.
- *
- * @return a string containing the @a breadcrumb output.
+ * @param $breadcrumb
+ *   An array containing the breadcrumb links.
+ * @return a string containing the breadcrumb output.
  */
 function theme_breadcrumb($breadcrumb) {
-  return "<div class=\"breadcrumb\">". implode($breadcrumb, ' &raquo; ') ."</div>";
+  return '<div class="breadcrumb">'. implode($breadcrumb, ' &raquo; ') .'</div>';
 }
 
 /**
- * Returns themed node.
- *
- * The passed $node object provides a all relevant information for displaying a
- * node:
- * @li @c $node->nid
- * @li @c $node->type i.e. story, blog, forum.
- * @li @c $node->title
- * @li @c $node->created a unix timestamp.
- * @li @c $node->teaser
- * @li @c $node->body
- * @li @c $node->changed a unix timestamp.
- * @li @c $node->uid the id of the poster.
- * @li @c $node->username the username of the poster.
- *
- * @param $node the @a node to be themed.
- * @param $main Display teaser only, as on main page?
- * @param $page Display node as standalone page (no title)?
- *
- * @return a string containing the @a node output.
+ * Return a themed node.
+ *
+ * @param $node
+ *   An object providing all relevant information for displaying a node:
+ *   - $node->nid: The ID of the node.
+ *   - $node->type: The content type (story, blog, forum...).
+ *   - $node->title: The title of the node.
+ *   - $node->created: The creation date, as a UNIX timestamp.
+ *   - $node->teaser: A shortened version of the node body.
+ *   - $node->body: The entire node contents.
+ *   - $node->changed: The last modification date, as a UNIX timestamp.
+ *   - $node->uid: The ID of the author.
+ *   - $node->username: The username of the author.
+ * @param $teaser
+ *   Whether to display the teaser only, as on the main page.
+ * @param $page
+ *   Whether to display the node as a standalone page. If TRUE, do not display
+ *   the title because it will be provided by the menu system.
+ * @return
+ *   A string containing the node output.
  */
-function theme_node($node, $main = 0, $page = 0) {
-  if (module_exist("taxonomy")) {
-    $terms = taxonomy_link("taxonomy terms", $node);
+function theme_node($node, $teaser = FALSE, $page = FALSE) {
+  if (module_exist('taxonomy')) {
+    $terms = taxonomy_link('taxonomy terms', $node);
   }
 
   if ($page == 0) {
-    $output = "<h2 class=\"title\">$node->title</h2> by ". format_name($node);
+    $output = '<h2 class="title">'. $node->title .'</h2> by '. format_name($node);
   }
   else {
-    $output = "by ". format_name($node);
+    $output = 'by '. format_name($node);
   }
 
   if (count($terms)) {
-    $output .= " <small>(". theme('links', $terms) .")</small><br />";
+    $output .= ' <small>('. theme('links', $terms) .')</small><br />';
   }
 
-  if ($main && $node->teaser) {
+  if ($teaser && $node->teaser) {
     $output .= $node->teaser;
   }
   else {
     $output .= $node->body;
   }
 
-  if ($links = link_node($node, $main)) {
-    $output .= "<div class=\"links\">". theme('links', $links) ."</div>";
+  if ($links = link_node($node, $teaser)) {
+    $output .= '<div class="links">'. theme('links', $links) .'</div>';
   }
 
   return $output;
 }
 
 /**
- * Returns themed form element.
+ * Return a themed form element.
  *
  * @param $title the form element's title
  * @param $value the form element's data
@@ -338,36 +346,44 @@ function theme_form_element($title, $value, $description = NULL, $id = NULL, $re
 
 
 /**
- * Returns themed sub menu, typically displayed under the tabs.
+ * Return a themed submenu, typically displayed under the tabs.
  *
- * @param $menus an associative array of links.
+ * @param $links
+ *   An array of links.
  */
-
 function theme_submenu($links) {
-  return "<div class=\"submenu\">". implode(' | ', $links) ."</div>";
+  return '<div class="submenu">'. implode(' | ', $links) .'</div>';
 }
 
 /**
- * Returns themed table.
- *
- * @param $header array of table header strings
- * @param $rows array of arrays containing the table cells
- * @param $attributes attribute array for the table tag
- *
- * @return a string representing the table.
+ * Return a themed table.
+ *
+ * @param $header
+ *   An array containing the table headers. Each element of the array can be
+ *   either a localized string or an associative array with the following keys:
+ *   - "data": The localized title of the table column.
+ *   - "field": The database field represented in the table column (required if
+ *     user is to be able to sort on this column).
+ *   - "sort": A default sort order for this column ("asc" or "desc").
+ *   - Any HTML attributes, such as "colspan", to apply to the column header cell.
+ * @param $rows
+ *   An array of arrays containing the table cells. Each cell can be either a
+ *   string or and associative array with the following keys:
+ *   - "data": The string to display in the table cell.
+ *   - Any HTML attributes, such as "colspan", to apply to the table cell.
+ * @param $attributes
+ *   An array of HTML attributes to apply to the table tag.
+ * @return
+ *   An HTML string representing the table.
  */
-
 function theme_table($header, $rows, $attributes = NULL) {
 
-  $output = "<table ". drupal_attributes($attributes) .">\n";
-
-  /*
-  ** Emit the table header:
-  */
+  $output = '<table '. drupal_attributes($attributes) .">\n";
 
+  // Format the table header:
   if (is_array($header)) {
     $ts = tablesort_init($header);
-    $output .= " <tr>";
+    $output .= ' <tr>';
     foreach ($header as $cell) {
       $cell = tablesort_header($cell, $header, $ts);
       $output .= _theme_table_cell($cell, 1);
@@ -375,27 +391,23 @@ function theme_table($header, $rows, $attributes = NULL) {
     $output .= " </tr>\n";
   }
 
-  /*
-  ** Emit the table rows:
-  */
-
+  // Format the table rows:
   if (is_array($rows)) {
-    $i = 0;
     foreach ($rows as $number => $row) {
       if ($number % 2 == 1) {
-        $output .= " <tr class=\"light\">";
+        $output .= ' <tr class="light">';
       }
       else {
-        $output .= " <tr class=\"dark\">";
+        $output .= ' <tr class="dark">';
       }
 
+      $i = 0;
       foreach ($row as $cell) {
         $cell = tablesort_cell($cell, $header, $ts, $i);
         $output .= _theme_table_cell($cell, 0);
         $i++;
       }
       $output .= " </tr>\n";
-      $i = 0;
     }
   }
 
@@ -404,32 +416,36 @@ function theme_table($header, $rows, $attributes = NULL) {
 }
 
 /**
- * Returns themed box.
- *
- * @param $title the @a subject of the box.
- * @param $content the @a content of the box.
- * @param $region the @a region of the box.
- *
- * @return a string containing the @a box output.
+ * Return a themed box.
+ *
+ * @param $title
+ *   The subject of the box.
+ * @param $content
+ *   The content of the box.
+ * @param $region
+ *   The region in which the box is displayed.
+ * @return
+ *   A string containing the box output.
  */
 function theme_box($title, $content, $region = 'main') {
-  $output = "<h2 class=\"title\">$title</h2><div>$content</div>";
+  $output = '<h2 class="title">'. $title .'</h2><div>'. $content .'</div>';
   return $output;
 }
 
 /**
- * Returns a themed block.
+ * Return a themed block.
  *
  * You can style your blocks by defining .block (all blocks),
  * .block-<i>module</i> (all blocks of module <i>module</i>), and
  * \#block-<i>module</i>-<i>delta</i> (specific block of module <i>module</i>
  * with delta <i>delta</i>) in your theme's CSS.
  *
- * @param $block object "indexed with" fields from database table 'blocks'
+ * @param $block
+ *   An object populated with fields from the "blocks" database table
  *   ($block->module, $block->delta, $block->region, ...) and fields returned by
- *   <i>module</i>_block("view") ($block->subject, $block->content, ...).
- *
- * @return a string containing the @a box output.
+ *   <i>module</i>_block('view') ($block->subject, $block->content, ...).
+ * @return
+ *   A string containing the block output.
  */
 function theme_block($block) {
   $output  = "<div class=\"block block-$block->module\" id=\"block-$block->module-$block->delta\">\n";
@@ -440,68 +456,72 @@ function theme_block($block) {
 }
 
 /**
- * Returns themed marker, useful for marking new comments or required form
+ * Return a themed marker, useful for marking new comments or required form
  * elements.
  *
- * @return a string containing the @a mark output.
+ * @return
+ *   A string containing the marker.
  */
 function theme_mark() {
   return '<span class="marker">*</span>';
 }
 
 /**
- * Returns themed list of items.
- *
- * @param $items (optional) an array of the items to be displayed in a list.
- * @param $title (optional) the title of the list.
- *
- * @return a string containing the @a list output.
+ * Return a themed list of items.
+ *
+ * @param $items
+ *   An array of items to be displayed in the list.
+ * @param $title
+ *   The title of the list.
+ * @return
+ *   A string containing the list output.
  */
 function theme_item_list($items = array(), $title = NULL) {
-  $output = "<div class=\"item-list\">";
+  $output = '<div class="item-list">';
   if (isset($title)) {
-    $output .= "<h3>$title</h3>";
+    $output .= '<h3>'. $title .'</h3>';
   }
 
   if (isset($items)) {
-    $output .= "<ul>";
+    $output .= '<ul>';
     foreach ($items as $item) {
-      $output .= "<li>$item</li>";
+      $output .= '<li>'. $item .'</li>';
     }
-    $output .= "</ul>";
+    $output .= '</ul>';
   }
-  $output .= "</div>";
+  $output .= '</div>';
   return $output;
 }
 
 /**
- * Returns themed error message.
+ * Return a themed error message.
  * REMOVE: this function is deprecated an no longer used in core.
  *
- * @param $message the error message to be themed.
+ * @param $message
+ *   The error message to be themed.
  *
- * @return a string containing the @a error output.
+ * @return
+ *   A string containing the error output.
  */
 function theme_error($message) {
-  return "<div class=\"error\">$message</div>";
+  return '<div class="error">'. $message .'</div>';
 }
 
 /**
- * Returns code that emits an XML-icon.
- *
- * @return a string containing the @a output.
+ * Return code that emits an XML icon.
  */
 function theme_xml_icon($url) {
-  return "<div class=\"xml-icon\"><a href=\"$url\"><img src=\"misc/xml.png\" width=\"36\" height=\"14\" alt=\"". t('XML feed') ."\" /></a></div>";
+  return '<div class="xml-icon"><a href="'. $url .'"><img src="misc/xml.png" width="36" height="14" alt="'. t('XML feed') .'" /></a></div>';
 }
 
 /**
- * Execute hook _footer() which is run at the end of the page right before the
- * \</body> tag.
+ * Execute hook_footer() which is run at the end of the page right before the
+ * close of the body tag.
  *
  * @param $main (optional)
  *
- * @return a string containing the @a closure output.
+ * @return
+ *   A string containing the results of the hook_footer() calls.
  */
 function theme_closure($main = 0) {
   $footer = module_invoke_all('footer', $main);
@@ -509,12 +529,13 @@ function theme_closure($main = 0) {
 }
 
 /**
- * Call _onload hook in all modules to enable modules to insert javascript that
+ * Call hook_onload() in all modules to enable modules to insert JavaScript that
  * will get run once the page has been loaded by the browser.
  *
- * @param $theme_onloads (optional) addition onload directives.
- *
- * @return a string containing the @a onload output.
+ * @param $theme_onloads
+ *   Additional onload directives.
+ * @return
+ *   A string containing the onload attributes.
  */
 function theme_onload_attribute($theme_onloads = array()) {
   if (!is_array($theme_onloads)) {
@@ -522,19 +543,20 @@ function theme_onload_attribute($theme_onloads = array()) {
   }
   // Merge theme onloads (javascript rollovers, image preloads, etc.)
   // with module onloads (htmlarea, etc.)
-  $onloads = array_merge(module_invoke_all("onload"), $theme_onloads);
+  $onloads = array_merge(module_invoke_all('onload'), $theme_onloads);
   if (count($onloads)) {
-    return " onload=\"" . implode("; ", $onloads) . "\"";
+    return ' onload="' . implode('; ', $onloads) . '"';
   }
   return '';
 }
 
 /**
- * Returns themed blocks available for current $user at $region.
- *
- * @param $region main|left|right
+ * Return a set of blocks available for the current user.
  *
- * @return a string containing the @a blocks output.
+ * @param $region
+ *   Which set of blocks to retrieve.
+ * @return
+ *   A string containing the themed blocks for this region.
  */
 function theme_blocks($region) {
   $output = '';
@@ -547,7 +569,9 @@ function theme_blocks($region) {
   }
   return $output;
 }
-/* @} */
+/**
+ * @} end of defgroup themeable
+ */
 
 function _theme_table_cell($cell, $header = 0) {
   $attributes = '';