diff --git includes/common.inc includes/common.inc
index d5a394d..4eeb58e 100644
--- includes/common.inc
+++ includes/common.inc
@@ -5410,7 +5410,7 @@ function element_get_visible_children(array $elements) {
 }
 
 /**
- * Provide theme registration for themes across .inc files.
+ * Register theme hooks across .inc files and specify default values for variables.
  */
 function drupal_common_theme() {
   return array(
diff --git includes/form.inc includes/form.inc
index 5f609f5..61cba98 100644
--- includes/form.inc
+++ includes/form.inc
@@ -1929,7 +1929,11 @@ function _form_options_flatten($array) {
 }
 
 /**
- * Theme select form element.
+ * Returns HTML for a select form element.
+ *
+ * It is possible to group options together; to do this, change the format of
+ * $options to an associative array in which the keys are group labels, and the
+ * values are associative arrays in the normal $options format.
  *
  * @param $variables
  *   An associative array containing:
@@ -1937,14 +1941,7 @@ function _form_options_flatten($array) {
  *     Properties used: #title, #value, #options, #description, #extra,
  *     #multiple, #required, #name, #attributes, #size.
  *
- * @return
- *   A themed HTML string representing the form element.
- *
  * @ingroup themeable
- *
- * It is possible to group options together; to do this, change the format of
- * $options to an associative array in which the keys are group labels, and the
- * values are associative arrays in the normal $options format.
  */
 function theme_select($variables) {
   $element = $variables['element'];
@@ -2049,7 +2046,7 @@ function form_get_options($element, $key) {
 }
 
 /**
- * Theme a fieldset form element.
+ * Returns HTML for a fieldset form element and its children.
  *
  * @param $variables
  *   An associative array containing:
@@ -2057,9 +2054,6 @@ function form_get_options($element, $key) {
  *     Properties used: #attributes, #children, #collapsed, #collapsible,
  *     #description, #id, #title, #value.
  *
- * @return
- *   A themed HTML string representing the group of items.
- *
  * @ingroup themeable
  */
 function theme_fieldset($variables) {
@@ -2084,7 +2078,7 @@ function theme_fieldset($variables) {
 }
 
 /**
- * Theme a radio button form element.
+ * Returns HTML for a radio button form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2092,9 +2086,6 @@ function theme_fieldset($variables) {
  *     Properties used: #required, #return_value, #value, #attributes, #title,
  *     #description
  *
- * @return
- *   A themed HTML string representing the form item group.
- *
  * @ingroup themeable
  */
 function theme_radio($variables) {
@@ -2111,7 +2102,7 @@ function theme_radio($variables) {
 }
 
 /**
- * Theme a set of radio button form elements.
+ * Returns HTML for a set of radio button form elements.
  *
  * @param $variables
  *   An associative array containing:
@@ -2119,9 +2110,6 @@ function theme_radio($variables) {
  *     Properties used: #title, #value, #options, #description, #required,
  *     #attributes, #children.
  *
- * @return
- *   A themed HTML string representing the radio button set.
- *
  * @ingroup themeable
  */
 function theme_radios($variables) {
@@ -2191,7 +2179,7 @@ function password_confirm_validate($element, &$element_state) {
 }
 
 /**
- * Theme a date selection form element.
+ * Returns HTML for a date selection form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2199,9 +2187,6 @@ function password_confirm_validate($element, &$element_state) {
  *     Properties used: #title, #value, #options, #description, #required,
  *     #attributes.
  *
- * @return
- *   A themed HTML string representing the date selection boxes.
- *
  * @ingroup themeable
  */
 function theme_date($variables) {
@@ -2330,7 +2315,7 @@ function form_process_radios($element) {
 }
 
 /**
- * Theme a checkbox form element.
+ * Returns HTML for a checkbox form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2338,9 +2323,6 @@ function form_process_radios($element) {
  *     Properties used: #title, #value, #return_value, #description, #required,
  *     #attributes.
  *
- * @return
- *   A themed HTML string representing the checkbox.
- *
  * @ingroup themeable
  */
 function theme_checkbox($variables) {
@@ -2362,16 +2344,13 @@ function theme_checkbox($variables) {
 }
 
 /**
- * Theme a set of checkbox form elements.
+ * Returns HTML for a set of checkbox form elements.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #children, #attributes.
  *
- * @return
- *   A themed HTML string representing the checkbox set.
- *
  * @ingroup themeable
  */
 function theme_checkboxes($variables) {
@@ -2456,14 +2435,12 @@ function form_process_container($element, &$form_state) {
 }
 
 /**
- * Adds a container for grouped items.
+ * Returns HTML for a container for grouped form items.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #id, #attributes, #children.
- * @return
- *   A themed HTML string representing the form element.
  *
  * @ingroup themeable
  */
@@ -2478,16 +2455,9 @@ function theme_container($variables) {
 }
 
 /**
- * Formats a table with radio buttons or checkboxes.
+ * Returns HTML for a table with radio buttons or checkboxes.
  *
- * @param $variables
- *   An associative array containing:
- *   - element: An associative array containing the properties and children of
- *     the tableselect element. Properties used: #header, #options, #empty,
- *     and #js_select. The #options property is an array of selection options;
- *     each array element of #options is an array of properties. These
- *     properties can include #attributes, which is added to the
- *     table row's HTML attributes (see theme_table()). Example:
+ * An example of per-row options:
  * @code
  * $options = array();
  * $options[0]['title'] = "A red row"
@@ -2502,8 +2472,14 @@ function theme_container($variables) {
  * );
  * @endcode
  *
- * @return
- *   A themed HTML string representing the table.
+ * @param $variables
+ *   An associative array containing:
+ *   - element: An associative array containing the properties and children of
+ *     the tableselect element. Properties used: #header, #options, #empty,
+ *     and #js_select. The #options property is an array of selection options;
+ *     each array element of #options is an array of properties. These
+ *     properties can include #attributes, which is added to the
+ *     table row's HTML attributes; see theme_table().
  *
  * @ingroup themeable
  */
@@ -2747,16 +2723,13 @@ function form_process_vertical_tabs($element, &$form_state) {
 }
 
 /**
- * Makes the element's children fieldsets be vertical tabs.
+ * Returns HTML for an element's children fieldsets as vertical tabs.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties and children of the
  *     fieldset. Properties used: #children.
  *
- * @return
- *   A themed HTML string representing the form element.
- *
  * @ingroup themeable
  */
 function theme_vertical_tabs($variables) {
@@ -2770,16 +2743,13 @@ function theme_vertical_tabs($variables) {
 }
 
 /**
- * Theme a submit button form element.
+ * Returns HTML for a submit button form element.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #attributes, #button_type, #name, #value.
  *
- * @return
- *   A themed HTML string representing the form element.
- *
  * @ingroup themeable
  */
 function theme_submit($variables) {
@@ -2788,16 +2758,13 @@ function theme_submit($variables) {
 }
 
 /**
- * Theme a button form element.
+ * Returns HTML for a button form element.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #attributes, #button_type, #name, #value.
  *
- * @return
- *   A themed HTML string representing the form element.
- *
  * @ingroup themeable
  */
 function theme_button($variables) {
@@ -2808,15 +2775,13 @@ function theme_button($variables) {
 }
 
 /**
- * Theme a image button form element.
+ * Returns HTML for an image button form element.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #attributes, #button_type, #name, #value, #title, #src.
  *
- * @return
- *   A themed HTML string representing the form element.
  * @ingroup themeable
  */
 function theme_image_button($variables) {
@@ -2833,16 +2798,13 @@ function theme_image_button($variables) {
 }
 
 /**
- * Theme a hidden form element.
+ * Returns HTML for a hidden form element.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #name, #value, #attributes.
  *
- * @return
- *   A themed HTML string representing the form element.
- *
  * @ingroup themeable
  */
 function theme_hidden($variables) {
@@ -2851,7 +2813,7 @@ function theme_hidden($variables) {
 }
 
 /**
- * Theme a textfield form element.
+ * Returns HTML for a textfield form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2859,9 +2821,6 @@ function theme_hidden($variables) {
  *     Properties used: #title, #value, #description, #size, #maxlength,
  *     #required, #attributes, #autocomplete_path.
  *
- * @return
- *   A themed HTML string representing the textfield.
- *
  * @ingroup themeable
  */
 function theme_textfield($variables) {
@@ -2885,16 +2844,13 @@ function theme_textfield($variables) {
 }
 
 /**
- * Theme a form.
+ * Returns HTML for a form.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #action, #method, #attributes, #children
  *
- * @return
- *   A themed HTML string representing the form.
- *
  * @ingroup themeable
  */
 function theme_form($variables) {
@@ -2905,7 +2861,7 @@ function theme_form($variables) {
 }
 
 /**
- * Theme a textarea form element.
+ * Returns HTML for a textarea form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2913,9 +2869,6 @@ function theme_form($variables) {
  *     Properties used: #title, #value, #description, #rows, #cols, #required,
  *     #attributes
  *
- * @return
- *   A themed HTML string representing the textarea.
- *
  * @ingroup themeable
  */
 function theme_textarea($variables) {
@@ -2941,7 +2894,7 @@ function theme_textarea($variables) {
 }
 
 /**
- * Theme a password form element.
+ * Returns HTML for a password form element.
  *
  * @param $variables
  *   An associative array containing:
@@ -2949,9 +2902,6 @@ function theme_textarea($variables) {
  *     Properties used: #title, #value, #description, #size, #maxlength,
  *     #required, #attributes.
  *
- * @return
- *   A themed HTML string representing the form element.
- *
  * @ingroup themeable
  */
 function theme_password($variables) {
@@ -2979,7 +2929,10 @@ function form_process_weight($element) {
 }
 
 /**
- * Theme a file upload form element.
+ * Returns HTML for a file upload form element.
+ *
+ * For assistance with handling the uploaded file correctly, see the API
+ * provided by file.inc.
  *
  * @param $variables
  *   An associative array containing:
@@ -2987,13 +2940,7 @@ function form_process_weight($element) {
  *     Properties used: #title, #name, #size, #description, #required,
  *     #attributes.
  *
- * @return
- *   A themed HTML string representing the field.
- *
  * @ingroup themeable
- *
- * For assistance with handling the uploaded file correctly, see the API
- * provided by file.inc.
  */
 function theme_file($variables) {
   $element = $variables['element'];
@@ -3002,7 +2949,7 @@ function theme_file($variables) {
 }
 
 /**
- * Theme a form element.
+ * Returns HTML for a form element.
  *
  * Each form element is wrapped in a DIV with #type and #name classes. In
  * addition to the element itself, the div contains a label before or after
@@ -3039,9 +2986,6 @@ function theme_file($variables) {
  *     Properties used: #title, #title_display, #description, #id, #required,
  *     #children, #type, #name.
  *
- * @return
- *   A string representing the form element.
- *
  * @ingroup themeable
  */
 function theme_form_element($variables) {
@@ -3102,13 +3046,11 @@ function theme_form_element($variables) {
 }
 
 /**
- * Theme the marker for required form elements.
+ * Returns HTML for a marker for required form elements.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
- * @return
- *   A string representing the marker to identify required form elements.
  *
  * @ingroup themeable
  */
@@ -3123,7 +3065,7 @@ function theme_form_required_marker($variables) {
 }
 
 /**
- * Theme a form element label and required marker.
+ * Returns HTML for a form element label and required marker.
  *
  * Form element labels include the #title and a #required marker. The label is
  * associated with the element itself by the element #id. Labels may appear
@@ -3141,8 +3083,6 @@ function theme_form_required_marker($variables) {
  *   An associative array containing:
  *   - element: An associative array containing the properties of the element.
  *     Properties used: #required, #title, #id, #value, #description.
- * @return
- *   A string representing the form element label.
  *
  * @ingroup themeable
  */
diff --git includes/menu.inc includes/menu.inc
index 6b6ed29..bd5a252 100644
--- includes/menu.inc
+++ includes/menu.inc
@@ -1374,22 +1374,20 @@ function _menu_tree_data(&$links, $parents, $depth) {
 /**
  * Preprocess the rendered tree for theme_menu_tree.
  *
- * @ingroup themeable
+ * @see theme_menu_tree()
  */
 function template_preprocess_menu_tree(&$variables) {
   $variables['tree'] = $variables['tree']['#children'];
 }
 
 /**
- * Theme wrapper for the HTML output for a menu sub-tree.
+ * Returns HTML for a wrapper for a menu sub-tree.
  *
  * @param $variables
  *   An associative array containing:
- *   - tree: @todo: document
- *
- * @return
- *   A themed HTML string.
+ *   - tree: An HTML string containing the tree's items.
  *
+ * @see template_preprocess_menu_tree()
  * @ingroup themeable
  */
 function theme_menu_tree($variables) {
@@ -1397,15 +1395,12 @@ function theme_menu_tree($variables) {
 }
 
 /**
- * Generate the HTML output for a menu link and submenu.
+ * Returns HTML for a menu link and submenu.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: Structured array data for a menu link.
  *
- * @return
- *   A themed HTML string.
- *
  * @ingroup themeable
  */
 function theme_menu_link(array $variables) {
@@ -1420,13 +1415,14 @@ function theme_menu_link(array $variables) {
 }
 
 /**
- * Generate the HTML output for a single local task link.
+ * Returns HTML for a single local task link.
  *
  * @param $variables
  *   An associative array containing:
- *   - #link: A menu link array with 'title', 'href', and 'localized_options'
- *     keys.
- *   - #active: A boolean indicating whether the local task is active.
+ *   - element: A render element containing:
+ *     - #link: A menu link array with 'title', 'href', and 'localized_options'
+ *       keys.
+ *     - #active: A boolean indicating whether the local task is active.
  *
  * @ingroup themeable
  */
@@ -1451,12 +1447,13 @@ function theme_menu_local_task($variables) {
 }
 
 /**
- * Generate the HTML output for a single local action link.
+ * Returns HTML for a single local action link.
  *
  * @param $variables
  *   An associative array containing:
- *   - #link: A menu link array with 'title', 'href', and 'localized_options'
- *     keys.
+ *   - element: A render element containing:
+ *     - #link: A menu link array with 'title', 'href', and 'localized_options'
+ *       keys.
  *
  * @ingroup themeable
  */
diff --git includes/pager.inc includes/pager.inc
index 12c9eed..1a29625 100644
--- includes/pager.inc
+++ includes/pager.inc
@@ -186,11 +186,11 @@ function pager_get_query_parameters() {
 }
 
 /**
- * Format a query pager.
+ * Returns HTML for 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.
- * Format a list of nearby pages with additional query results.
+ * retrieve a pager control so that users can view other results. Format a list
+ * of nearby pages with additional query results.
  *
  * @param $variables
  *   An associative array containing:
@@ -201,9 +201,6 @@ function pager_get_query_parameters() {
  *     the pager links.
  *   - quantity: The number of pages in the list.
  *
- * @return
- *   An HTML string that generates the query pager.
- *
  * @ingroup themeable
  */
 function theme_pager($variables) {
@@ -321,7 +318,7 @@ function theme_pager($variables) {
  */
 
 /**
- * Format a "first page" link.
+ * Returns HTML for the "first page" link in a query pager.
  *
  * @param $variables
  *   An associative array containing:
@@ -331,9 +328,6 @@ function theme_pager($variables) {
  *   - parameters: 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.
- *
  * @ingroup themeable
  */
 function theme_pager_first($variables) {
@@ -352,7 +346,7 @@ function theme_pager_first($variables) {
 }
 
 /**
- * Format a "previous page" link.
+ * Returns HTML for the "previous page" link in a query pager.
  *
  * @param $variables
  *   An associative array containing:
@@ -363,9 +357,6 @@ function theme_pager_first($variables) {
  *   - parameters: 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.
- *
  * @ingroup themeable
  */
 function theme_pager_previous($variables) {
@@ -394,7 +385,7 @@ function theme_pager_previous($variables) {
 }
 
 /**
- * Format a "next page" link.
+ * Returns HTML for the "next page" link in a query pager.
  *
  * @param $variables
  *   An associative array containing:
@@ -405,9 +396,6 @@ function theme_pager_previous($variables) {
  *   - parameters: 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.
- *
  * @ingroup themeable
  */
 function theme_pager_next($variables) {
@@ -435,7 +423,7 @@ function theme_pager_next($variables) {
 }
 
 /**
- * Format a "last page" link.
+ * Returns HTML for the "last page" link in query pager.
  *
  * @param $variables
  *   An associative array containing:
@@ -445,9 +433,6 @@ function theme_pager_next($variables) {
  *   - parameters: 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.
- *
  * @ingroup themeable
  */
 function theme_pager_last($variables) {
@@ -467,7 +452,7 @@ function theme_pager_last($variables) {
 
 
 /**
- * Format a link to a specific query result page.
+ * Returns HTML for a link to a specific query result page.
  *
  * @param $variables
  *   An associative array containing:
@@ -479,9 +464,6 @@ function theme_pager_last($variables) {
  *   - attributes: An associative array of HTML attributes to apply to a pager
  *     anchor tag.
  *
- * @return
- *   An HTML string that generates the link.
- *
  * @ingroup themeable
  */
 function theme_pager_link($variables) {
diff --git includes/theme.inc includes/theme.inc
index e481e38..750cf18 100644
--- includes/theme.inc
+++ includes/theme.inc
@@ -105,27 +105,23 @@ function drupal_theme_initialize() {
 }
 
 /**
- * Initialize the theme system given already loaded information. This
- * function is useful to initialize a theme when no database is present.
+ * Initialize the theme system given already loaded information.
+ *
+ * This function is useful to initialize a theme when no database is present.
  *
  * @param $theme
  *   An object with the following information:
- *     filename
- *       The .info file for this theme. The 'path' to
- *       the theme will be in this file's directory. (Required)
- *     owner
- *       The path to the .theme file or the .engine file to load for
- *       the theme. (Required)
- *     stylesheet
- *       The primary stylesheet for the theme. (Optional)
- *     engine
- *       The name of theme engine to use. (Optional)
+ *   - filename: The .info file for this theme. The 'path' to the theme will be
+ *     in this file's directory. (Required)
+ *   - owner: The path to the .theme file or the .engine file to load for the
+ *     theme. (Required)
+ *   - stylesheet: The primary stylesheet for the theme. (Optional)
+ *   - engine: The name of theme engine to use. (Optional)
  * @param $base_theme
- *    An optional array of objects that represent the 'base theme' if the
- *    theme is meant to be derivative of another theme. It requires
- *    the same information as the $theme object. It should be in
- *    'oldest first' order, meaning the top level of the chain will
- *    be first.
+ *   An optional array of objects that represent the 'base theme' if the theme
+ *   is meant to be derivative of another theme. It requires the same
+ *   information as the $theme object. It should be in 'oldest first' order,
+ *   meaning the top level of the chain will be first.
  * @param $registry_callback
  *   The callback to invoke to set the theme registry.
  */
@@ -228,6 +224,7 @@ function _drupal_theme_initialize($theme, $base_theme = array(), $registry_callb
 
 /**
  * Get the theme registry.
+ *
  * @return
  *   The theme registry array if it has been stored in memory, NULL otherwise.
  */
@@ -237,10 +234,11 @@ function theme_get_registry() {
 
 /**
  * Store the theme registry in memory.
+ *
  * @param $registry
- *   A registry array as returned by _theme_build_registry()
+ *   A registry array as returned by _theme_build_registry().
  * @return
- *   The theme registry array stored in memory
+ *   The theme registry array stored in memory.
  */
 function _theme_set_registry($registry = NULL) {
   static $theme_registry = NULL;
@@ -274,7 +272,7 @@ function _theme_load_registry($theme, $base_theme = NULL, $theme_engine = NULL)
     // If not, build one and cache it.
     $registry = _theme_build_registry($theme, $base_theme, $theme_engine);
    // Only persist this registry if all modules are loaded. This assures a
-   // complete set of theme hooks.
+   // complete set of theming hooks.
     if (module_load_all(NULL)) {
       _theme_save_registry($theme, $registry);
       _theme_set_registry($registry);
@@ -290,9 +288,10 @@ function _theme_save_registry($theme, $registry) {
 }
 
 /**
- * Force the system to rebuild the theme registry; this should be called
- * when modules are added to the system, or when a dynamic system needs
- * to add more theme hooks.
+ * Force the system to rebuild the theme registry.
+ *
+ * This should be called when modules are added to the system, or when a dynamic
+ * system needs to add more theming hooks.
  */
 function drupal_theme_rebuild() {
   cache_clear_all('theme_registry', 'cache', TRUE);
@@ -303,7 +302,7 @@ function drupal_theme_rebuild() {
  *
  * @param $cache
  *   The theme registry that will eventually be cached; It is an associative
- *   array keyed by theme hooks, whose values are associative arrays describing
+ *   array keyed by theming hooks, whose values are associative arrays describing
  *   the hook:
  *   - 'type': The passed in $type.
  *   - 'theme path': The passed in $path.
@@ -453,7 +452,7 @@ function _theme_process_registry(&$cache, $name, $type, $theme, $path) {
       }
     }
 
-    // Merge the newly created theme hooks into the existing cache.
+    // Merge the newly created theming hooks into the existing cache.
     $cache = array_merge($cache, $result);
   }
 
@@ -496,7 +495,7 @@ function _theme_process_registry(&$cache, $name, $type, $theme, $path) {
  */
 function _theme_build_registry($theme, $base_theme, $theme_engine) {
   $cache = array();
-  // First, process the theme hooks advertised by modules. This will
+  // First, process the theming hooks advertised by modules. This will
   // serve as the basic registry.
   foreach (module_implements('theme') as $module) {
     _theme_process_registry($cache, $module, 'module', $module, drupal_get_path('module', $module));
@@ -617,15 +616,20 @@ function list_themes($refresh = FALSE) {
 /**
  * Generate the themed output.
  *
- * All requests for theme hooks must go through this function. It examines
- * the request and routes it to the appropriate theme function. The theme
+ * All requests for theming hooks must go through this function. It examines
+ * the request and routes it to the appropriate implementation. The theme
  * registry is checked to determine which implementation to use, which may
  * be a function or a template.
  *
- * If the implementation is a template, the following functions may be used to
- * modify the $variables array. They are processed in two distinct phases;
- * "preprocess" and "process" functions. The order listed here is the order in
- * which they execute.
+ * The following functions may be used to modify the $variables array. They are
+ * processed in two distinct phases; "preprocess" and "process" functions. The
+ * order listed below is the order in which they execute.
+ *
+ * However, if the implementation is a theme function, only the hook-specific
+ * preprocess and process functions (the ones ending in _HOOK) are called from
+ * the following list. This is because theme functions need to be fast, and
+ * calling the multi-hook preprocess and process functions (the ones not ending
+ * in _HOOK) for them would incur a noticeable performance penalty.
  *
  * - template_preprocess(&$variables)
  *   This sets a default set of variables for all template implementations.
@@ -647,7 +651,7 @@ function list_themes($refresh = FALSE) {
  *
  * - ENGINE_engine_preprocess(&$variables)
  *   This function should only be implemented by theme engines and exists
- *   so that it can set necessary variables for all hooks.
+ *   so that it can set necessary variables for all templates.
  *
  * - ENGINE_engine_preprocess_HOOK(&$variables)
  *   This is the same as the previous function, but it is called for a single
@@ -689,22 +693,6 @@ function list_themes($refresh = FALSE) {
  *   This is the same as the previous function, but it is called for a single
  *   theming hook.
  *
- * - ENGINE_process(&$variables)
- *   This is meant to be used by themes that utilize a theme engine. It is
- *   provided so that the processor is not locked into a specific theme.
- *   This makes it easy to share and transport code but theme authors must be
- *   careful to prevent fatal re-declaration errors when using sub-themes that
- *   have their own processor named exactly the same as its base theme. In
- *   the default theme engine (PHPTemplate), sub-themes will load their own
- *   template.php file in addition to the one used for its parent theme. This
- *   increases the risk for these errors. A good practice is to use the engine
- *   name for the base theme and the theme name for the sub-themes to minimize
- *   this possibility.
- *
- * - ENGINE_process_HOOK(&$variables)
- *   The same applies from the previous function, but it is called for a
- *   specific hook.
- *
  * - THEME_process(&$variables)
  *   These functions are based upon the raw theme; they should primarily be
  *   used by themes that do not use an engine or by sub-themes. It serves the
@@ -714,12 +702,6 @@ function list_themes($refresh = FALSE) {
  *   The same applies from the previous function, but it is called for a
  *   specific hook.
  *
- * If the implementation is a function, only the hook-specific preprocess
- * and process functions (the ones ending in _HOOK) are called from the
- * above list. This is because theme hooks with function implementations
- * need to be fast, and calling the non-hook-specific preprocess and process
- * functions for them would incur a noticeable performance penalty.
- *
  * There are two special variables that these preprocess and process functions
  * can set:
  *   'theme_hook_suggestion' and 'theme_hook_suggestions'. These will be merged
@@ -746,8 +728,8 @@ function list_themes($refresh = FALSE) {
  *   - links__contextual
  *   - links
  *   This allows themes to create specific theme implementations for named
- *   objects and contexts of otherwise generic theme hooks. The $hook parameter
- *   may also be an array, in which case the first hook that has an
+ *   objects and contexts of otherwise generic theming hooks. The $hook
+ *   parameter may also be an array, in which case the first hook that has an
  *   implementation is used. This allows for the code that calls theme() to
  *   explicitly specify the fallback order in a situation where using the '__'
  *   convention is not desired or insufficient.
@@ -756,8 +738,9 @@ function list_themes($refresh = FALSE) {
  *   An associative array of variables to merge with defaults from the theme
  *   registry, pass to preprocess and process functions for modification, and
  *   finally, pass to the function or template implementing the theme hook.
- *   Alternatively, this can be a renderable array, in which case, its properties
- *   are mapped to variables expected by the theme hook implementations.
+ *   Alternatively, this can be a renderable array, in which case, its
+ *   properties are mapped to variables expected by the theme hook
+ *   implementations.
  *
  * @return
  *   An HTML string that generates the themed output.
@@ -954,12 +937,12 @@ function theme($hook, $variables = array()) {
 /**
  * Return the path to the current themed element.
  *
- * It can point to the active theme or the module handling a themed implementation.
- * For example, when invoked within the scope of a theming call it will depend
- * on where the theming function is handled. If implemented from a module, it
- * will point to the module. If implemented from the active theme, it will point
- * to the active theme. When called outside the scope of a theming call, it will
- * always point to the active theme.
+ * It can point to the active theme or the module handling a themed
+ * implementation. For example, when invoked within the scope of a theming call
+ * it will depend on where the theming function is handled. If implemented from
+ * a module, it will point to the module. If implemented from the active theme,
+ * it will point to the active theme. When called outside the scope of a theming
+ * call, it will always point to the active theme.
  */
 function path_to_theme() {
   global $theme_path;
@@ -975,7 +958,7 @@ function path_to_theme() {
  * Allow themes and/or theme engines to easily discover overridden theme functions.
  *
  * @param $cache
- *   The existing cache of theme hooks to test against.
+ *   The existing cache of theming hooks to test against.
  * @param $prefixes
  *   An array of prefixes to test, in reverse order of importance.
  *
@@ -989,7 +972,7 @@ function drupal_find_theme_functions($cache, $prefixes) {
   foreach ($cache as $hook => $info) {
     foreach ($prefixes as $prefix) {
       // Find theme functions that implement possible "suggestion" variants of
-      // registered theme hooks and add those as new registered theme hooks.
+      // registered theming hooks and add those as new registered theming hooks.
       // The 'pattern' key defines a common prefix that all suggestions must
       // start with. The default is the name of the hook followed by '__'. An
       // 'base hook' key is added to each entry made for a found suggestion,
@@ -1014,9 +997,9 @@ function drupal_find_theme_functions($cache, $prefixes) {
           }
         }
       }
-      // Find theme functions that implement registered theme hooks and include
-      // that in what is returned so that the registry knows that the theme has
-      // this implementation.
+      // Find theme functions that implement registered theming hooks and
+      // include that in what is returned so that the registry knows that the
+      // theme has this implementation.
       if (function_exists($prefix . '_' . $hook)) {
         $implementations[$hook] = array(
           'function' => $prefix . '_' . $hook,
@@ -1032,7 +1015,7 @@ function drupal_find_theme_functions($cache, $prefixes) {
  * Allow themes and/or theme engines to easily discover overridden templates.
  *
  * @param $cache
- *   The existing cache of theme hooks to test against.
+ *   The existing cache of theming hooks to test against.
  * @param $extension
  *   The extension that these templates will have.
  * @param $path
@@ -1065,7 +1048,7 @@ function drupal_find_theme_templates($cache, $extension, $path) {
   // Get a listing of all template files in the path to search.
   $files = drupal_system_listing($regex, $path, 'name', 0);
 
-  // Find templates that implement registered theme hooks and include that in
+  // Find templates that implement registered theming hooks and include that in
   // what is returned so that the registry knows that the theme has this
   // implementation.
   foreach ($files as $template => $file) {
@@ -1091,7 +1074,7 @@ function drupal_find_theme_templates($cache, $extension, $path) {
   }
 
   // Find templates that implement possible "suggestion" variants of registered
-  // theme hooks and add those as new registered theme hooks. See
+  // theming hooks and add those as new registered theming hooks. See
   // drupal_find_theme_functions() for more information about suggestions and
   // the use of 'pattern' and 'base hook'.
   $patterns = array_keys($files);
@@ -1329,8 +1312,7 @@ function theme_disable($theme_list) {
  */
 
 /**
- * Return a themed set of status and/or error messages. The messages are grouped
- * by type.
+ * Returns HTML for status and/or error messages, grouped by type.
  *
  * An invisible heading identifies the messages for assistive technology.
  * Sighted users see a colored box. See http://www.w3.org/TR/WCAG-TECHS/H69.html
@@ -1340,9 +1322,6 @@ function theme_disable($theme_list) {
  *   An associative array containing:
  *   - display: (optional) Set to 'status' or 'error' to display only messages
  *     of that type.
- *
- * @return
- *   A string containing the messages.
  */
 function theme_status_messages($variables) {
   $display = $variables['display'];
@@ -1374,11 +1353,11 @@ function theme_status_messages($variables) {
 }
 
 /**
- * Return a themed link.
+ * Returns HTML for a link.
  *
  * All Drupal code that outputs a link should call the l() function. That
- * function performs some initial preprocessing, and then, if necessary,
- * calls theme('link') for rendering the anchor tag.
+ * function performs some initial preprocessing, and then, if necessary, calls
+ * theme('link') for rendering the anchor tag.
  *
  * To optimize performance for sites that don't need custom theming of links,
  * the l() function includes an inline copy of this function, and uses that copy
@@ -1386,11 +1365,8 @@ function theme_status_messages($variables) {
  * or process functions or override this theme implementation.
  *
  * @param $variables
- *   An associative array containing the keys 'text', 'path', and 'options'.
- *   See the l() function for information about these variables.
- *
- * @return
- *   An HTML string containing a link to the given path.
+ *   An associative array containing the keys 'text', 'path', and 'options'. See
+ *   the l() function for information about these variables.
  *
  * @see l()
  */
@@ -1399,28 +1375,29 @@ function theme_link($variables) {
 }
 
 /**
- * Return a themed set of links.
+ * Returns HTML for a set of links.
  *
  * @param $variables
  *   An associative array containing:
  *   - links: A keyed array of links to be themed. The key for each link is used
  *     as its css class. Each link should be itself an array, with the following
  *     keys:
- *      - title: the link text
- *      - href: the link URL. If omitted, the 'title' is shown as a plain text
- *        item in the links list.
- *      - html: (optional) set this to TRUE if 'title' is HTML so it will be
- *        escaped.
+ *     - title: the link text
+ *     - href: the link URL. If omitted, the 'title' is shown as a plain text
+ *       item in the links list.
+ *     - html: (optional) set this to TRUE if 'title' is HTML so it will be
+ *       escaped.
  *     Array items are passed on to the l() function's $options parameter when
  *     creating the link.
  *   - attributes: A keyed array of attributes.
  *   - heading: An optional keyed array or a string for a heading to precede the
  *     links. When using an array the following keys can be used:
- *      - text: the heading text
- *      - level: the heading level (e.g. 'h2', 'h3')
- *      - class: (optional) an array of the CSS classes for the heading
+ *     - text: the heading text
+ *     - level: the heading level (e.g. 'h2', 'h3')
+ *     - class: (optional) an array of the CSS classes for the heading
  *     When using a string it will be used as the text of the heading and the
  *     level will default to 'h2'.
+ *
  *     Headings should be used on navigation menus and any list of links that
  *     consistently appears on multiple pages. To make the heading invisible
  *     use the 'element-invisible' CSS class. Do not use 'display:none', which
@@ -1428,9 +1405,6 @@ function theme_link($variables) {
  *     screen-reader and keyboard only users to navigate to or skip the links.
  *     See http://juicystudio.com/article/screen-readers-display-none.php
  *     and http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.
- *
- * @return
- *   A string containing an unordered list of links.
  */
 function theme_links($variables) {
   $links = $variables['links'];
@@ -1509,7 +1483,7 @@ function theme_links($variables) {
 }
 
 /**
- * Return a themed image.
+ * Returns HTML for an image.
  *
  * @param $variables
  *   An associative array containing:
@@ -1521,9 +1495,6 @@ function theme_links($variables) {
  *   - attributes: Associative array of attributes to be placed in the img tag.
  *   - getsize: If set to TRUE, the image's dimension are fetched and added as
  *     width/height attributes.
- *
- * @return
- *   A string containing the image tag.
  */
 function theme_image($variables) {
   $path = $variables['path'];
@@ -1540,14 +1511,11 @@ function theme_image($variables) {
 }
 
 /**
- * Return a themed breadcrumb trail.
+ * Returns HTML for a breadcrumb trail.
  *
  * @param $variables
  *   An associative array containing:
  *   - breadcrumb: An array containing the breadcrumb links.
- *
- * @return
- *   A string containing the breadcrumb output.
  */
 function theme_breadcrumb($variables) {
   $breadcrumb = $variables['breadcrumb'];
@@ -1563,7 +1531,7 @@ function theme_breadcrumb($variables) {
 }
 
 /**
- * Return a themed table.
+ * Returns HTML for a table.
  *
  * @param $variables
  *   An associative array containing:
@@ -1634,9 +1602,6 @@ function theme_breadcrumb($variables) {
  *   - sticky: Use a "sticky" table header.
  *   - empty: The message to display in an extra row if table does not have any
  *     rows.
- *
- * @return
- *   An HTML string representing the table.
  */
 function theme_table($variables) {
   $header = $variables['header'];
@@ -1763,7 +1728,10 @@ function theme_table($variables) {
 }
 
 /**
- * Returns a header cell for tables that have a select all functionality.
+ * Returns attributes for a header cell of tables with select all functionality.
+ *
+ * @return
+ *   An array of attributes.
  */
 function theme_table_select_header_cell() {
   drupal_add_js('misc/tableselect.js');
@@ -1772,14 +1740,11 @@ function theme_table_select_header_cell() {
 }
 
 /**
- * Return a themed sort icon.
+ * Returns HTML for a sort icon.
  *
  * @param $variables
  *   An associative array containing:
- *   - style: Set to either asc or desc. This sets which icon to show.
- *
- * @return
- *   A themed sort icon.
+ *   - style: Set to either 'asc' or 'desc', this determines which icon to show.
  */
 function theme_tablesort_indicator($variables) {
   if ($variables['style'] == "asc") {
@@ -1791,16 +1756,12 @@ function theme_tablesort_indicator($variables) {
 }
 
 /**
- * Return a themed marker, useful for marking new or updated
- * content.
+ * Returns HTML for a marker for new or updated content.
  *
  * @param $variables
  *   An associative array containing:
  *   - type: Number representing the marker type to display. See MARK_NEW,
  *     MARK_UPDATED, MARK_READ.
- *
- * @return
- *   A string containing the marker.
  */
 function theme_mark($variables) {
   $type = $variables['type'];
@@ -1816,7 +1777,7 @@ function theme_mark($variables) {
 }
 
 /**
- * Return a themed list of items.
+ * Returns HTML for a list or nested list of items.
  *
  * @param $variables
  *   An associative array containing:
@@ -1829,9 +1790,6 @@ function theme_mark($variables) {
  *   - title: The title of the list.
  *   - type: The type of list to return (e.g. "ul", "ol").
  *   - attributes: The attributes applied to the list element.
- *
- * @return
- *   A string containing the list output.
  */
 function theme_item_list($variables) {
   $items = $variables['items'];
@@ -1885,14 +1843,18 @@ function theme_item_list($variables) {
 }
 
 /**
- * Returns code that emits the 'more help'-link.
+ * Returns HTML for a "more help" link.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - url: The url for the link.
  */
 function theme_more_help_link($variables) {
   return '<div class="more-help-link">' . t('<a href="@link">More help</a>', array('@link' => check_url($variables['url']))) . '</div>';
 }
 
 /**
- * Return code that emits an feed icon.
+ * Returns HTML for a feed icon.
  *
  * @param $variables
  *   An associative array containing:
@@ -1907,15 +1869,12 @@ function theme_feed_icon($variables) {
 }
 
 /**
- * Generate the output for a generic HTML tag with attributes.
- *
- * This theme function should be used for tags appearing in the HTML HEAD of a
- * document (specified via the #tag property in the passed $element):
+ * Returns HTML for a generic HTML tag with attributes.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array describing the tag:
- *     - #tag: The tag name to output.  Typical tags added to the HTML HEAD:
+ *     - #tag: The tag name to output. Typical tags added to the HTML HEAD:
  *       - meta: To provide meta information, such as a page refresh.
  *       - link: To refer to stylesheets and other contextual information.
  *       - script: To load JavaScript.
@@ -1947,96 +1906,19 @@ function theme_html_tag($variables) {
 }
 
 /**
- * Returns code that emits the 'more' link used on blocks.
+ * Returns HTML for a "more" link, like those used in blocks.
  *
  * @param $variables
  *   An associative array containing:
- *   - url: The url of the main page
- *   - title: A descriptive verb for the link, like 'Read more'
+ *   - url: The url of the main page.
+ *   - title: A descriptive verb for the link, like 'Read more'.
  */
 function theme_more_link($variables) {
   return '<div class="more-link">' . t('<a href="@link" title="@title">More</a>', array('@link' => check_url($variables['url']), '@title' => $variables['title'])) . '</div>';
 }
 
 /**
- * Preprocess variables for theme_username().
- *
- * Modules that make any changes to variables like 'name' or 'extra' must insure
- * that the final string is safe to include directly in the output by using
- * check_plain() or filter_xss().
- *
- * @see theme_username()
- */
-function template_preprocess_username(&$variables) {
-  $account = $variables['account'];
-
-  $variables['extra'] = '';
-  if (empty($account->uid)) {
-   $variables['uid'] = 0;
-   if (theme_get_setting('toggle_comment_user_verification')) {
-     $variables['extra'] = ' (' . t('not verified') . ')';
-   }
-  }
-  else {
-    $variables['uid'] = (int)$account->uid;
-  }
-
-  // Set the name to a formatted name that is safe for printing and
-  // that won't break tables by being too long. Keep an unshortened,
-  // unsanitized version, in case other preprocess functions want to implement
-  // their own shortening logic or add markup. If they do so, they must ensure
-  // that $variables['name'] is safe for printing.
-  $name = $variables['name_raw'] = format_username($account);
-  if (drupal_strlen($name) > 20) {
-    $name = drupal_substr($name, 0, 15) . '...';
-  }
-  $variables['name'] = check_plain($name);
-
-  $variables['profile_access'] = user_access('access user profiles');
-  $variables['link_attributes'] = array();
-  // Populate link path and attributes if appropriate.
-  if ($variables['uid'] && $variables['profile_access']) {
-    // We are linking to a local user.
-    $variables['link_attributes'] = array('title' => t('View user profile.'));
-    $variables['link_path'] = 'user/' . $variables['uid'];
-  }
-  elseif (!empty($account->homepage)) {
-    // Like the 'class' attribute, the 'rel' attribute can hold a
-    // space-separated set of values, so initialize it as an array to make it
-    // easier for other preprocess functions to append to it.
-    $variables['link_attributes'] = array('rel' => array('nofollow'));
-    $variables['link_path'] = $account->homepage;
-    $variables['homepage'] = $account->homepage;
-  }
-  // We do not want the l() function to check_plain() a second time.
-  $variables['link_options']['html'] = TRUE;
-  // Set a default class.
-  $variables['attributes_array'] = array('class' => array('username'));
-}
-
-/**
- * Process variables for theme_username().
- *
- * @see theme_username()
- */
-function template_process_username(&$variables) {
-  // Finalize the link_options array for passing to the l() function.
-  // This is done in the process phase so that attributes may be added by
-  // modules or the theme during the preprocess phase.
-  if (isset($variables['link_path'])) {
-    // $variables['attributes_array'] contains attributes that should be applied
-    // regardless of whether a link is being rendered or not.
-    // $variables['link_attributes'] contains attributes that should only be
-    // applied if a link is being rendered. Preprocess functions are encouraged
-    // to use the former unless they want to add attributes on the link only.
-    // If a link is being rendered, these need to be merged. Some attributes are
-    // themselves arrays, so the merging needs to be recursive.
-    $variables['link_options']['attributes'] = array_merge_recursive($variables['link_attributes'], $variables['attributes_array']);
-  }
-}
-
-/**
- * Format a username.
+ * Returns HTML for a username, potentially linked to the user's page.
  *
  * @param $variables
  *   An associative array containing:
@@ -2050,10 +1932,6 @@ function template_process_username(&$variables) {
  *   - attributes_array: An array of attributes to pass to the
  *     drupal_attributes() function if not linking to the user's page.
  *
- * @return
- *   A themed HTML string containing the user's name, potentially linked to the
- *   user's page.
- *
  * @see template_preprocess_username()
  * @see template_process_username()
  */
@@ -2074,15 +1952,12 @@ function theme_username($variables) {
 }
 
 /**
- * Return a themed progress bar.
+ * Returns HTML for a progress bar.
  *
  * @param $variables
  *   An associative array containing:
  *   - percent: The percentage of the progress.
  *   - message: A string containing information to be displayed.
- *
- * @return
- *   A themed HTML string representing the progress bar.
  */
 function theme_progress_bar($variables) {
   $output = '<div id="progress" class="progress">';
@@ -2095,14 +1970,11 @@ function theme_progress_bar($variables) {
 }
 
 /**
- * Create a standard indentation div. Used for drag and drop tables.
+ * Returns HTML for an indentation div; used for drag and drop tables.
  *
  * @param $variables
  *   An associative array containing:
  *   - size: Optional. The number of indentations to create.
- *
- * @return
- *   A string containing indentations.
  */
 function theme_indentation($variables) {
   $output = '';
@@ -2146,6 +2018,7 @@ function _theme_table_cell($cell, $header = FALSE) {
 
 /**
  * Adds a default set of helper variables for variable processors and templates.
+ *
  * This comes in before any other preprocess function which makes it possible to
  * be used in default theme implementations (non-overridden theme functions).
  */
@@ -2309,7 +2182,7 @@ function template_preprocess_html(&$variables) {
 }
 
 /**
- * Preprocess variables for page.tpl.php
+ * Preprocess variables for page.tpl.php.
  *
  * Most themes utilize their own copy of page.tpl.php. The default is located
  * inside "modules/system/page.tpl.php". Look in there for the full list of
@@ -2322,7 +2195,6 @@ function template_preprocess_html(&$variables) {
  * template_preprocess_maintenance_page() to keep all of them consistent.
  *
  * @see drupal_render_page()
- * @see template_process_page()
  * @see page.tpl.php
  */
 function template_preprocess_page(&$variables) {
@@ -2370,7 +2242,7 @@ function template_preprocess_page(&$variables) {
   }
 }
 /**
- * Process variables for html.tpl.php
+ * Process variables for html.tpl.php.
  *
  * Perform final addition and modification of variables before passing into
  * the template. To customize these variables, call drupal_render() on elements
@@ -2417,7 +2289,7 @@ function template_process_html(&$variables) {
  */
 function theme_get_suggestions($args, $base, $delimiter = '__') {
 
-  // Build a list of suggested theme hooks or body classes in order of
+  // Build a list of suggested theming hooks or body classes in order of
   // specificity. One suggestion is made for every element of the current path,
   // though numeric elements are not carried to subsequent suggestions. For
   // example, for $base='page', http://www.example.com/node/1/edit would result
@@ -2452,10 +2324,12 @@ function theme_get_suggestions($args, $base, $delimiter = '__') {
 }
 
 /**
- * The variables array generated here is a mirror of template_preprocess_page().
- * This preprocessor will run its course when theme_maintenance_page() is
- * invoked. It is also used in theme_install_page() and theme_update_page() to
- * keep all the variables consistent.
+ * Preprocess variables for maintenance-page.tpl.php.
+ *
+ * The variables array generated here is a mirror of template_preprocess_page()
+ * and template_preprocess_html(). This preprocessor will run its course when
+ * theme_maintenance_page() is invoked. It is also used in theme_install_page()
+ * and theme_update_page() to keep all the variables consistent.
  *
  * An alternate template file of "maintenance-page--offline.tpl.php" can be
  * used when the database is offline to hide errors and completely replace the
@@ -2550,7 +2424,9 @@ function template_preprocess_maintenance_page(&$variables) {
 }
 
 /**
- * The variables array generated here is a mirror of template_process_html().
+ * Process variables for maintenance-page.tpl.php.
+ *
+ * The variables array generated here is a mirror of template_preprocess_page().
  * This processor will run its course when theme_maintenance_page() is invoked.
  * It is also used in theme_install_page() and theme_update_page() to keep all
  * the variables consistent.
@@ -2565,7 +2441,7 @@ function template_process_maintenance_page(&$variables) {
 }
 
 /**
- * Preprocess variables for region.tpl.php
+ * Preprocess variables for region.tpl.php.
  *
  * Prepare the values passed to the theme_region function to be passed into a
  * pluggable template engine. Uses the region name to generate a template file
@@ -2583,3 +2459,82 @@ function template_preprocess_region(&$variables) {
   $variables['classes_array'][] = $region;
   $variables['theme_hook_suggestions'][] = 'region__' . $region;
 }
+
+/**
+ * Preprocess variables for theme_username().
+ *
+ * Modules that make any changes to variables like 'name' or 'extra' must insure
+ * that the final string is safe to include directly in the output by using
+ * check_plain() or filter_xss().
+ *
+ * @see theme_username()
+ * @see template_process_username()
+ */
+function template_preprocess_username(&$variables) {
+  $account = $variables['account'];
+
+  $variables['extra'] = '';
+  if (empty($account->uid)) {
+   $variables['uid'] = 0;
+   if (theme_get_setting('toggle_comment_user_verification')) {
+     $variables['extra'] = ' (' . t('not verified') . ')';
+   }
+  }
+  else {
+    $variables['uid'] = (int)$account->uid;
+  }
+
+  // Set the name to a formatted name that is safe for printing and
+  // that won't break tables by being too long. Keep an unshortened,
+  // unsanitized version, in case other preprocess functions want to implement
+  // their own shortening logic or add markup. If they do so, they must ensure
+  // that $variables['name'] is safe for printing.
+  $name = $variables['name_raw'] = format_username($account);
+  if (drupal_strlen($name) > 20) {
+    $name = drupal_substr($name, 0, 15) . '...';
+  }
+  $variables['name'] = check_plain($name);
+
+  $variables['profile_access'] = user_access('access user profiles');
+  $variables['link_attributes'] = array();
+  // Populate link path and attributes if appropriate.
+  if ($variables['uid'] && $variables['profile_access']) {
+    // We are linking to a local user.
+    $variables['link_attributes'] = array('title' => t('View user profile.'));
+    $variables['link_path'] = 'user/' . $variables['uid'];
+  }
+  elseif (!empty($account->homepage)) {
+    // Like the 'class' attribute, the 'rel' attribute can hold a
+    // space-separated set of values, so initialize it as an array to make it
+    // easier for other preprocess functions to append to it.
+    $variables['link_attributes'] = array('rel' => array('nofollow'));
+    $variables['link_path'] = $account->homepage;
+    $variables['homepage'] = $account->homepage;
+  }
+  // We do not want the l() function to check_plain() a second time.
+  $variables['link_options']['html'] = TRUE;
+  // Set a default class.
+  $variables['attributes_array'] = array('class' => array('username'));
+}
+
+/**
+ * Process variables for theme_username().
+ *
+ * @see theme_username()
+ * @see template_preprocess_username()
+ */
+function template_process_username(&$variables) {
+  // Finalize the link_options array for passing to the l() function.
+  // This is done in the process phase so that attributes may be added by
+  // modules or the theme during the preprocess phase.
+  if (isset($variables['link_path'])) {
+    // $variables['attributes_array'] contains attributes that should be applied
+    // regardless of whether a link is being rendered or not.
+    // $variables['link_attributes'] contains attributes that should only be
+    // applied if a link is being rendered. Preprocess functions are encouraged
+    // to use the former unless they want to add attributes on the link only.
+    // If a link is being rendered, these need to be merged. Some attributes are
+    // themselves arrays, so the merging needs to be recursive.
+    $variables['link_options']['attributes'] = array_merge_recursive($variables['link_attributes'], $variables['attributes_array']);
+  }
+}
diff --git includes/theme.maintenance.inc includes/theme.maintenance.inc
index 5ae8cf5..bacab00 100644
--- includes/theme.maintenance.inc
+++ includes/theme.maintenance.inc
@@ -87,7 +87,12 @@ function _theme_load_offline_registry($theme, $base_theme = NULL, $theme_engine
 }
 
 /**
- * Return a themed list of maintenance tasks to perform.
+ * Returns HTML for a list of maintenance tasks to perform.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - items: An associative array of maintenance tasks.
+ *   - active: The key for the currently active maintenance task.
  *
  * @ingroup themeable
  */
@@ -120,7 +125,7 @@ function theme_task_list($variables) {
 }
 
 /**
- * Generate a themed installation page.
+ * Returns HTML for the installation page.
  *
  * Note: this function is not themeable.
  *
@@ -180,7 +185,7 @@ function theme_install_page($variables) {
 }
 
 /**
- * Generate a themed update page.
+ * Returns HTML for the update page.
  *
  * Note: this function is not themeable.
  *
@@ -226,10 +231,13 @@ function theme_update_page($variables) {
 }
 
 /**
- * Generate a report of the results from an operation run via authorize.php.
+ * Returns HTML for a report of the results from an operation run via authorize.php.
  *
- * @param array $variables
+ * @param $variables
+ *   An associative array containing:
  *   - messages: An array of result messages.
+ *
+ * @ingroup themeable
  */
 function theme_authorize_report($variables) {
   $messages = $variables['messages'];
@@ -251,11 +259,14 @@ function theme_authorize_report($variables) {
 }
 
 /**
- * Render a single log message from the authorize.php batch operation.
+ * Returns HTML for a single log message from the authorize.php batch operation.
  *
  * @param $variables
+ *   An associative array containing:
  *   - message: The log message.
  *   - success: A boolean indicating failure or success.
+ *
+ * @ingroup themeable
  */
 function theme_authorize_message($variables) {
   $output = '';
diff --git modules/aggregator/aggregator-feed-source.tpl.php modules/aggregator/aggregator-feed-source.tpl.php
index 267265e..0215b80 100644
--- modules/aggregator/aggregator-feed-source.tpl.php
+++ modules/aggregator/aggregator-feed-source.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present the source of the feed.
+ * HTML for the source of a feed.
  *
  * The contents are rendered above feed listings when browsing source feeds.
  * For example, "example.com/aggregator/sources/1".
@@ -18,6 +18,7 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_feed_source()
+ * @ingroup themeable
  */
 ?>
 <div class="feed-source">
diff --git modules/aggregator/aggregator-item.tpl.php modules/aggregator/aggregator-item.tpl.php
index 5d6912f..ea367b6 100644
--- modules/aggregator/aggregator-item.tpl.php
+++ modules/aggregator/aggregator-item.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to format an individual feed item for display
- * on the aggregator page.
+ * HTML for an individual feed item for display on the aggregator page.
  *
  * Available variables:
  * - $feed_url: URL to the originating feed item.
@@ -17,6 +16,7 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_item()
+ * @ingroup themeable
  */
 ?>
 <div class="feed-item">
diff --git modules/aggregator/aggregator-summary-item.tpl.php modules/aggregator/aggregator-summary-item.tpl.php
index 281aa2f..73b0c09 100644
--- modules/aggregator/aggregator-summary-item.tpl.php
+++ modules/aggregator/aggregator-summary-item.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present a linked feed item for summaries.
+ * HTML for a linked feed item for summaries.
  *
  * Available variables:
  * - $feed_url: Link to originating feed.
@@ -14,6 +14,7 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_summary_item()
+ * @ingroup themeable
  */
 ?>
 <a href="<?php print $feed_url; ?>"><?php print $feed_title; ?></a>
diff --git modules/aggregator/aggregator-summary-items.tpl.php modules/aggregator/aggregator-summary-items.tpl.php
index a8b6b7b..12363c3 100644
--- modules/aggregator/aggregator-summary-items.tpl.php
+++ modules/aggregator/aggregator-summary-items.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present feeds as list items.
+ * HTML for a list of feed items.
  *
  * Each iteration generates a single feed source or category.
  *
@@ -15,6 +15,7 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_summary-items()
+ * @ingroup themeable
  */
 ?>
 <h3><?php print $title; ?></h3>
diff --git modules/aggregator/aggregator-wrapper.tpl.php modules/aggregator/aggregator-wrapper.tpl.php
index f49dce3..d35de5e 100644
--- modules/aggregator/aggregator-wrapper.tpl.php
+++ modules/aggregator/aggregator-wrapper.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to wrap aggregator content.
+ * HTML for a wrapper for aggregator content.
  *
  * Available variables:
  * - $content: All aggregator content.
@@ -11,6 +11,7 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_aggregator_wrapper()
+ * @ingroup themeable
  */
 ?>
 <div id="aggregator">
diff --git modules/aggregator/aggregator.module modules/aggregator/aggregator.module
index a57e52f..0c72339 100644
--- modules/aggregator/aggregator.module
+++ modules/aggregator/aggregator.module
@@ -703,15 +703,13 @@ function aggregator_category_load($cid) {
 }
 
 /**
- * Format an individual feed item for display in the block.
+ * Returns HTML for an individual feed item for display in the block.
  *
  * @param $variables
  *   An associative array containing:
  *   - item: The item to be displayed.
  *   - feed: Not used.
  *
- * @return
- *   The item HTML.
  * @ingroup themeable
  */
 function theme_aggregator_block_item($variables) {
diff --git modules/aggregator/aggregator.pages.inc modules/aggregator/aggregator.pages.inc
index 4b58067..ecd66f5 100644
--- modules/aggregator/aggregator.pages.inc
+++ modules/aggregator/aggregator.pages.inc
@@ -234,14 +234,12 @@ function aggregator_categorize_items_submit($form, &$form_state) {
 }
 
 /**
- * Theme the page list form for assigning categories.
+ * Returns HTML for the aggregator page list form for assigning categories.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An associative array containing the structure of the form.
+ *   - form: A render element representing the form.
  *
- * @return
- *   The output HTML.
  * @ingroup themeable
  */
 function theme_aggregator_categorize_items($variables) {
@@ -371,12 +369,13 @@ function aggregator_page_rss() {
 }
 
 /**
- * Theme the RSS output.
+ * Prints the RSS page for a feed.
  *
  * @param $variables
  *   An associative array containing:
  *   - feeds: An array of the feeds to theme.
  *   - category: A common category, if any, for all the feeds.
+ * @return void
  *
  * @ingroup themeable
  */
@@ -437,11 +436,12 @@ function aggregator_page_opml($cid = NULL) {
 }
 
 /**
- * Theme the OPML feed output.
+ * Prints the OPML page for a feed.
  *
  * @param $variables
  *   An associative array containing:
  *   - feeds: An array of the feeds to theme.
+ * @return void
  *
  * @ingroup themeable
  */
diff --git modules/block/block-admin-display-form.tpl.php modules/block/block-admin-display-form.tpl.php
index 5ec8be0..e154377 100644
--- modules/block/block-admin-display-form.tpl.php
+++ modules/block/block-admin-display-form.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to configure blocks.
+ * HTML for the block administration form.
  *
  * Available variables:
  * - $block_regions: An array of regions. Keyed by name with the title as value.
@@ -22,6 +22,7 @@
  *
  * @see template_preprocess_block_admin_display_form()
  * @see theme_block_admin_display()
+ * @ingroup themeable
  */
 ?>
 <?php
diff --git modules/block/block.tpl.php modules/block/block.tpl.php
index c4b71e9..816f799 100644
--- modules/block/block.tpl.php
+++ modules/block/block.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a block.
+ * HTML for a block.
  *
  * Available variables:
  * - $block->subject: Block title.
@@ -39,6 +39,7 @@
  * @see template_preprocess()
  * @see template_preprocess_block()
  * @see template_process()
+ * @ingroup themeable
  */
 ?>
 <div id="block-<?php print $block->module . '-' . $block->delta; ?>" class="<?php print $classes; ?>"<?php print $attributes; ?>>
diff --git modules/book/book-all-books-block.tpl.php modules/book/book-all-books-block.tpl.php
index 1282ce0..efa4aea 100644
--- modules/book/book-all-books-block.tpl.php
+++ modules/book/book-all-books-block.tpl.php
@@ -3,13 +3,16 @@
 
 /**
  * @file
- * Default theme implementation for rendering book outlines within a block.
- * This template is used only when the block is configured to "show block on
- * all pages" which presents Multiple independent books on all pages.
+ * HTML for the book outlines within a block.
+ *
+ * This template is only used when the block is configured to "show block on all
+ * pages" which presents multiple independent books on all pages.
  *
  * Available variables:
  * - $book_menus: Array of book outlines keyed to the parent book ID. Call
  *   render() on each to print it as an unordered list.
+ *
+ * @ingroup themeable
  */
 ?>
 <?php foreach ($book_menus as $book_id => $menu) : ?>
diff --git modules/book/book-export-html.tpl.php modules/book/book-export-html.tpl.php
index 23e5b15..ffc8b47 100644
--- modules/book/book-export-html.tpl.php
+++ modules/book/book-export-html.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for printed version of book outline.
+ * HTML for a printed version of a book outline.
  *
  * Available variables:
  * - $title: Top level node title.
@@ -15,6 +15,7 @@
  *   book-node-export-html.tpl.php.
  *
  * @see template_preprocess_book_export_html()
+ * @ingroup themeable
  */
 ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
diff --git modules/book/book-navigation.tpl.php modules/book/book-navigation.tpl.php
index 1d9dd08..ccb462d 100644
--- modules/book/book-navigation.tpl.php
+++ modules/book/book-navigation.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to navigate books. Presented under nodes that
- * are a part of book outlines.
+ * HTML for book navigation; presented under nodes that are a part of book outlines.
  *
  * Available variables:
  * - $tree: The immediate children of the current node rendered as an
@@ -28,6 +27,7 @@
  *   Provided as an option. Not used by default.
  *
  * @see template_preprocess_book_navigation()
+ * @ingroup themeable
  */
 ?>
 <?php if ($tree || $has_links): ?>
diff --git modules/book/book-node-export-html.tpl.php modules/book/book-node-export-html.tpl.php
index 6a00c67..ab5aac4 100644
--- modules/book/book-node-export-html.tpl.php
+++ modules/book/book-node-export-html.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for rendering a single node in a printer
- * friendly outline.
+ * HTML for a single book node in a printer friendly outline.
  *
  * @see book-node-export-html.tpl.php
  * Where it is collected and printed out.
@@ -16,6 +15,7 @@
  * - $children: All the child nodes recursively rendered through this file.
  *
  * @see template_preprocess_book_node_export_html()
+ * @ingroup themeable
  */
 ?>
 <div id="node-<?php print $node->nid; ?>" class="section-<?php print $depth; ?>">
diff --git modules/book/book.admin.inc modules/book/book.admin.inc
index 8ed7216..1d4c2ae 100644
--- modules/book/book.admin.inc
+++ modules/book/book.admin.inc
@@ -212,10 +212,14 @@ function _book_admin_table_tree($tree, &$form) {
 }
 
 /**
- * Theme function for the book administration page form.
+ * Returns HTML for a book administration form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
- * @ingroup themeable
  * @see book_admin_table()
+ * @ingroup themeable
  */
 function theme_book_admin_table($variables) {
   $form = $variables['form'];
diff --git modules/book/book.module modules/book/book.module
index 0b9d1d7..ecdb296 100644
--- modules/book/book.module
+++ modules/book/book.module
@@ -338,7 +338,11 @@ function book_block_save($delta = '', $edit = array()) {
 }
 
 /**
- * Generate the HTML output for a link to a book title when used as a block title.
+ * Returns HTML for a link to a book title when used as a block title.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - link: An array containing title, href and options for the link.
  *
  * @ingroup themeable
  */
diff --git modules/color/color.module modules/color/color.module
index bf1ce78..bb2cb34 100644
--- modules/color/color.module
+++ modules/color/color.module
@@ -222,7 +222,11 @@ function color_scheme_form($complete_form, &$form_state, $theme) {
 }
 
 /**
- * Theme the color form.
+ * Returns HTML for a theme's color form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/comment/comment-wrapper.tpl.php modules/comment/comment-wrapper.tpl.php
index 7b9119e..54349ab 100644
--- modules/comment/comment-wrapper.tpl.php
+++ modules/comment/comment-wrapper.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to wrap comments.
+ * HTML for a wrapper for comments.
  *
  * Available variables:
  * - $content: The array of content-related elements for the node. Use
@@ -28,6 +28,7 @@
  *
  * @see template_preprocess_comment_wrapper()
  * @see theme_comment_wrapper()
+ * @ingroup themeable
  */
 ?>
 <div id="comments" class="<?php print $classes; ?>"<?php print $attributes; ?>>
diff --git modules/comment/comment.module modules/comment/comment.module
index 9d2d609..0fe668d 100644
--- modules/comment/comment.module
+++ modules/comment/comment.module
@@ -568,10 +568,8 @@ function comment_new_page_count($num_comments, $new_replies, $node) {
 }
 
 /**
- * Returns a formatted list of recent comments to be displayed in the comment block.
+ * Returns HTML for a list of recent comments to be displayed in the comment block.
  *
- * @return
- *   The comment list HTML.
  * @ingroup themeable
  */
 function theme_comment_block() {
@@ -2205,7 +2203,7 @@ function template_preprocess_comment(&$variables) {
 }
 
 /**
- * Theme a "you can't post comments" notice.
+ * Returns HTML for a "you can't post comments" notice.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/comment/comment.tpl.php modules/comment/comment.tpl.php
index 287a931..6493e89 100644
--- modules/comment/comment.tpl.php
+++ modules/comment/comment.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for comments.
+ * HTML for a comment.
  *
  * Available variables:
  * - $author: Comment author. Can be link or plain text.
@@ -54,6 +54,7 @@
  * @see template_preprocess_comment()
  * @see template_process()
  * @see theme_comment()
+ * @ingroup themeable
  */
 ?>
 <div class="<?php print $classes; ?> clearfix"<?php print $attributes; ?>>
diff --git modules/dashboard/dashboard.module modules/dashboard/dashboard.module
index 9758f3c..f0e6560 100644
--- modules/dashboard/dashboard.module
+++ modules/dashboard/dashboard.module
@@ -366,13 +366,12 @@ function dashboard_update() {
 }
 
 /**
- * Theme the entire dashboard.
+ * Returns HTML for the entire dashboard.
  *
  * @param $variables
- *   - element: An associative array containing the properties of the dashboard region
- *              element. Properties used: #dashboard_region, #children
- * @return
- *   A string representing the themed dashboard.
+ *   An associative array containing:
+ *   - element: A render element containing the properties of the dashboard
+ *     region element, #dashboard_region and #children.
  *
  * @ingroup themeable
  */
@@ -383,15 +382,11 @@ function theme_dashboard($variables) {
 }
 
 /**
- * Theme the page containing the dashboard.
+ * Returns HTML for the non-customizable part of the dashboard page.
  *
  * @param $variables
  *   An associative array containing:
- *   - elements: An associative array containing the properties of the element.
- *     Properties used: #message
- * @return
- *   A themed HTML string representing the non-customizable part of the
- *   dashboard page.
+ *   - element: A render element containing a #message.
  *
  * @ingroup themeable
  */
@@ -402,13 +397,12 @@ function theme_dashboard_admin($variables) {
 }
 
 /**
- * Theme a generic dashboard region.
+ * Returns HTML for a generic dashboard region.
  *
  * @param $variables
- *   - element: An associative array containing the properties of the dashboard region
- *              element. Properties used: #dashboard_region, #children
- * @return
- *   A string representing the themed dashboard region.
+ *   An associative array containing:
+ *   - element: A render element containing the properties of the dashboard
+ *     region element, #dashboard_region and #children.
  *
  * @ingroup themeable
  */
@@ -425,13 +419,11 @@ function theme_dashboard_region($variables) {
 }
 
 /**
- * Theme a set of disabled blocks, for display in dashboard customization mode.
+ * Returns HTML for a set of disabled blocks, for display in dashboard customization mode.
  *
  * @param $variables
+ *   An associative array containing:
  *   - blocks: An array of block objects from _block_rehash().
- * @return
- *   A string representing the disabled blocks region of the dashboard
- *   customization page.
  *
  * @ingroup themeable
  */
@@ -447,12 +439,11 @@ function theme_dashboard_disabled_blocks($variables) {
 }
 
 /**
- * Theme a disabled block, for display in dashboard customization mode.
+ * Returns HTML for a disabled block, for display in dashboard customization mode.
  *
  * @param $variables
+ *   An associative array containing:
  *   - block: A block object from _block_rehash().
- * @return
- *   A string representing the disabled block.
  *
  * @ingroup themeable
  */
diff --git modules/dblog/dblog.admin.inc modules/dblog/dblog.admin.inc
index cd987e5..fc6fe97 100644
--- modules/dblog/dblog.admin.inc
+++ modules/dblog/dblog.admin.inc
@@ -251,7 +251,7 @@ function dblog_filters() {
 }
 
 /**
- * Formats a log message for display.
+ * Returns HTML for a log message.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/field/field.form.inc modules/field/field.form.inc
index 8c8874e..6c71472 100644
--- modules/field/field.form.inc
+++ modules/field/field.form.inc
@@ -231,10 +231,16 @@ function field_multiple_value_form($field, $instance, $langcode, $items, &$form,
 }
 
 /**
- * Theme an individual form element.
+ * Returns HTML for an individual form element.
  *
  * Combine multiple values into a table with drag-n-drop reordering.
  * TODO : convert to a template.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the form element.
+ *
+ * @ingroup themeable
  */
 function theme_field_multiple_value_form($variables) {
   $element = $variables['element'];
diff --git modules/field/field.module modules/field/field.module
index 5d9c159..5d2639f 100644
--- modules/field/field.module
+++ modules/field/field.module
@@ -790,7 +790,7 @@ function template_process_field(&$variables, $hook) {
  */
 
 /**
- * Returns a themed field.
+ * Returns HTML for a field.
  *
  * This is the default theme implementation to display the value of a field.
  * Theme developers who are comfortable with overriding theme functions may do
@@ -831,6 +831,18 @@ function template_process_field(&$variables, $hook) {
  * the exact performance impact depends on the server configuration and the
  * details of the website.
  *
+ * @param $variables
+ *   An associative array containing:
+ *   - label_hidden: A boolean indicating to show or hide the field label.
+ *   - title_attributes: A string containing the attributes for the title.
+ *   - label: The label for the field.
+ *   - content_attributes: A string containing the attaributes for the content's
+ *     div.
+ *   - items: An array of field items.
+ *   - item_attributes: An array of attributes for each item.
+ *   - classes: A string containing the classes for the wrapping div.
+ *   - attributes: A string containing the attributes for the wrapping div.
+ *
  * @see template_preprocess_field()
  * @see template_process_field()
  * @see field.tpl.php
diff --git modules/field/modules/options/options.module modules/field/modules/options/options.module
index 2a8d382..6a3c38e 100644
--- modules/field/modules/options/options.module
+++ modules/field/modules/options/options.module
@@ -366,8 +366,15 @@ function options_field_widget_error($element, $error, $form, &$form_state) {
 }
 
 /**
- *  Theme the label for the empty value for options that are not required.
- *  The default theme will display N/A for a radio list and blank for a select.
+ * Returns HTML for the label for the empty value for options that are not required.
+ *
+ * The default theme will display N/A for a radio list and blank for a select.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - instance: An array representing the widget requesting the options.
+ *
+ * @ingroup themeable
  */
 function theme_options_none($variables) {
   $instance = $variables['instance'];
diff --git modules/field/theme/field.tpl.php modules/field/theme/field.tpl.php
index 56502f0..1e6c169 100644
--- modules/field/theme/field.tpl.php
+++ modules/field/theme/field.tpl.php
@@ -2,8 +2,8 @@
 // $Id: field.tpl.php,v 1.13 2010/03/26 17:14:45 dries Exp $
 
 /**
- * @file field.tpl.php
- * Default template implementation to display the value of a field.
+ * @file
+ * HTML for a field.
  *
  * This file is not used and is here as a starting point for customization only.
  * @see theme_field()
@@ -41,6 +41,7 @@
  *
  * @see template_preprocess_field()
  * @see theme_field()
+ * @ingroup themeable
  */
 ?>
 <!--
diff --git modules/field_ui/field_ui-display-overview-form.tpl.php modules/field_ui/field_ui-display-overview-form.tpl.php
index fee7801..0637574 100644
--- modules/field_ui/field_ui-display-overview-form.tpl.php
+++ modules/field_ui/field_ui-display-overview-form.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to configure field display settings.
+ * HTML for the configurartion form for field display settings.
  *
  * Available variables:
  *
@@ -17,6 +17,7 @@
  *
  * @see field_ui_display_overview_form()
  * @see template_preprocess_field_ui_display_overview_form()
+ * @ingroup themeable
  */
 ?>
 <?php if ($rows): ?>
diff --git modules/field_ui/field_ui-field-overview-form.tpl.php modules/field_ui/field_ui-field-overview-form.tpl.php
index d710731..e1b4f79 100644
--- modules/field_ui/field_ui-field-overview-form.tpl.php
+++ modules/field_ui/field_ui-field-overview-form.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to configure field settings.
+ * HTML for the overview form for field settings.
  *
  * Available variables:
  *
@@ -17,6 +17,7 @@
  *
  * @see field_ui_field_overview_form()
  * @see template_preprocess_field_ui_field_overview_form()
+ * @ingroup themeable
  */
 ?>
 <table id="field-overview" class="sticky-enabled">
diff --git modules/file/file.field.inc modules/file/file.field.inc
index 31e4ce9..1f5a872 100644
--- modules/file/file.field.inc
+++ modules/file/file.field.inc
@@ -696,7 +696,13 @@ function file_field_widget_process_multiple($element, &$form_state, $form) {
 }
 
 /**
- * Theme an individual file upload widget.
+ * Returns HTML for an individual file upload widget.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the widget.
+ *
+ * @ingroup themeable
  */
 function theme_file_widget($variables) {
   $element = $variables['element'];
@@ -715,7 +721,13 @@ function theme_file_widget($variables) {
 }
 
 /**
- * Theme a group of file upload widgets.
+ * Returns HTML for a group of file upload widgets.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the widgets.
+ *
+ * @ingroup themeable
  */
 function theme_file_widget_multiple($variables) {
   $element = $variables['element'];
@@ -800,7 +812,7 @@ function theme_file_widget_multiple($variables) {
 }
 
 /**
- * Generate help text based on upload validators.
+ * Returns HTML for help text based on file upload validators.
  *
  * @param $variables
  *   An associative array containing:
@@ -809,8 +821,7 @@ function theme_file_widget_multiple($variables) {
  *   - upload_validators: An array of upload validators as used in
  *     $element['#upload_validators'].
  *
- * @return
- *   A string suitable for a file field description.
+ * @ingroup themeable
  */
 function theme_file_upload_help($variables) {
   $description = $variables['description'];
@@ -882,7 +893,13 @@ function file_field_formatter_view($entity_type, $entity, $field, $instance, $la
 }
 
 /**
- * Theme function for the 'table' formatter.
+ * Returns HTML for a file attachments table.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - items: An array of file attachments.
+ *
+ * @ingroup themeable
  */
 function theme_file_formatter_table($variables) {
   $header = array(t('Attachment'), t('Size'));
diff --git modules/file/file.module modules/file/file.module
index c8b1fd0..812dea7 100644
--- modules/file/file.module
+++ modules/file/file.module
@@ -607,7 +607,13 @@ function file_managed_file_save_upload($element) {
 }
 
 /**
- * Theme a managed file element.
+ * Returns HTML for a managed file element.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the file.
+ *
+ * @ingroup themeable
  */
 function theme_file_managed_file($variables) {
   $element = $variables['element'];
@@ -621,11 +627,13 @@ function theme_file_managed_file($variables) {
 }
 
 /**
- * Output a link to a file.
+ * Returns HTML for a link to a file.
  *
  * @param $variables
  *   An associative array containing:
  *   - file: A file object to which the link will be created.
+ *
+ * @ingroup themeable
  */
 function theme_file_link($variables) {
   $file = $variables['file'];
@@ -654,11 +662,13 @@ function theme_file_link($variables) {
 }
 
 /**
- * Return an image with an appropriate icon for the given file.
+ * Returns HTML for an image with an appropriate icon for the given file.
  *
  * @param $variables
  *   An associative array containing:
  *   - file: A file object for which to make an icon.
+ *
+ * @ingroup themeable
  */
 function theme_file_icon($variables) {
   $file = $variables['file'];
diff --git modules/filter/filter.admin.inc modules/filter/filter.admin.inc
index 3f4fd76..7b22123 100644
--- modules/filter/filter.admin.inc
+++ modules/filter/filter.admin.inc
@@ -56,7 +56,11 @@ function filter_admin_overview_submit($form, &$form_state) {
 }
 
 /**
- * Theme the text format administration overview form.
+ * Returns HTML for the text format administration overview form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -233,7 +237,11 @@ function filter_admin_format_form($form, &$form_state, $format) {
 }
 
 /**
- * Theme text format filter order form elements as tabledrag.
+ * Returns HTML for a text format's filter order form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/filter/filter.module modules/filter/filter.module
index 2e942fa..11c4c5c 100644
--- modules/filter/filter.module
+++ modules/filter/filter.module
@@ -933,15 +933,11 @@ function filter_form_access_denied($element) {
 }
 
 /**
- * Render a text format-enabled form element.
+ * Returns HTML for a text format-enabled form element.
  *
  * @param $variables
  *   An associative array containing:
- *   - element: An associative array containing the properties of the element.
- *     Properties used: #children, #description
- *
- * @return
- *   A string representing the form element.
+ *   - element: A render element containing #children and #description.
  *
  * @ingroup themeable
  */
@@ -1103,7 +1099,7 @@ function filter_dom_serialize_escape_cdata_element($dom_document, $dom_element,
 }
 
 /**
- * Format a link to the more extensive filter tips.
+ * Returns HTML for a link to the more extensive filter tips.
  *
  * @ingroup themeable
  */
@@ -1112,7 +1108,7 @@ function theme_filter_tips_more_info() {
 }
 
 /**
- * Format guidelines for a text format.
+ * Returns HTML for guidelines for a text format.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/filter/filter.pages.inc modules/filter/filter.pages.inc
index 1add777..13724ee 100644
--- modules/filter/filter.pages.inc
+++ modules/filter/filter.pages.inc
@@ -23,7 +23,7 @@ function filter_tips_long() {
 
 
 /**
- * Render HTML for a set of filter tips.
+ * Returns HTML for a set of filter tips.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/forum/forum-icon.tpl.php modules/forum/forum-icon.tpl.php
index 2499799..56199cd 100644
--- modules/forum/forum-icon.tpl.php
+++ modules/forum/forum-icon.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display an appropriate icon for a forum post.
+ * HTML for an appropriate icon for a forum post.
  *
  * Available variables:
  * - $new_posts: Indicates whether or not the topic contains new posts.
@@ -12,6 +12,7 @@
  *
  * @see template_preprocess_forum_icon()
  * @see theme_forum_icon()
+ * @ingroup themeable
  */
 ?>
 <?php if ($new_posts): ?>
diff --git modules/forum/forum-list.tpl.php modules/forum/forum-list.tpl.php
index 0c9cbcf..cc7a0d4 100644
--- modules/forum/forum-list.tpl.php
+++ modules/forum/forum-list.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a list of forums and containers.
+ * HTML for a list of forums and containers.
  *
  * Available variables:
  * - $forums: An array of forums and containers to display. It is keyed to the
@@ -29,6 +29,7 @@
  *
  * @see template_preprocess_forum_list()
  * @see theme_forum_list()
+ * @ingroup themeable
  */
 ?>
 <table id="forum-<?php print $forum_id; ?>">
diff --git modules/forum/forum-submitted.tpl.php modules/forum/forum-submitted.tpl.php
index d67e9cc..409355f 100644
--- modules/forum/forum-submitted.tpl.php
+++ modules/forum/forum-submitted.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to format a simple string indicated when and
- * by whom a topic was submitted.
+ * HTML for a simple string indicated when and by whom a topic was submitted.
  *
  * Available variables:
  *
@@ -15,6 +14,7 @@
  *
  * @see template_preprocess_forum_submitted()
  * @see theme_forum_submitted()
+ * @ingroup themeable
  */
 ?>
 <?php if ($time): ?>
diff --git modules/forum/forum-topic-list.tpl.php modules/forum/forum-topic-list.tpl.php
index 9c8ce3e..d19faca 100644
--- modules/forum/forum-topic-list.tpl.php
+++ modules/forum/forum-topic-list.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a list of forum topics.
+ * HTML for a list of forum topics.
  *
  * Available variables:
  * - $header: The table header. This is pre-generated with click-sorting
@@ -32,6 +32,7 @@
  *
  * @see template_preprocess_forum_topic_list()
  * @see theme_forum_topic_list()
+ * @ingroup themeable
  */
 ?>
 <table id="forum-topic-<?php print $topic_id; ?>">
diff --git modules/forum/forum.admin.inc modules/forum/forum.admin.inc
index 7a06ba8..c9a5161 100644
--- modules/forum/forum.admin.inc
+++ modules/forum/forum.admin.inc
@@ -102,14 +102,15 @@ function forum_form_submit($form, &$form_state) {
 }
 
 /**
- * Theme forum forms.
+ * Returns HTML for a forum form.
  *
  * By default this does not alter the appearance of a form at all,
  * but is provided as a convenience for themers.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An associative array containing the structure of the form.
+ *   - form: A render element representing the form.
+ *
  * @ingroup themeable
  */
 function theme_forum_form($variables) {
diff --git modules/forum/forums.tpl.php modules/forum/forums.tpl.php
index eee9b9f..bf5076d 100644
--- modules/forum/forums.tpl.php
+++ modules/forum/forums.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a forum which may contain forum
- * containers as well as forum topics.
+ * HTML for a forum which may contain forum containers as well as forum topics.
  *
  * Variables available:
  * - $forums: The forums to display (as processed by forum-list.tpl.php)
@@ -13,6 +12,7 @@
  *
  * @see template_preprocess_forums()
  * @see theme_forums()
+ * @ingroup themeable
  */
 ?>
 <?php if ($forums_defined): ?>
diff --git modules/image/image.admin.inc modules/image/image.admin.inc
index 508f771..f61790b 100644
--- modules/image/image.admin.inc
+++ modules/image/image.admin.inc
@@ -623,7 +623,7 @@ function image_rotate_form($data) {
 }
 
 /**
- * Display the page containing the list of image styles.
+ * Returns HTML for the page containing the list of image styles.
  *
  * @param $variables
  *   An associative array containing:
@@ -674,11 +674,11 @@ function theme_image_style_list($variables) {
 }
 
 /**
- * Theme callback for listing the effects within a specific image style.
+ * Returns HTML for a listing of the effects within a specific image style.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An associative array containing the structure of the effects group.
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -733,7 +733,7 @@ function theme_image_style_effects($variables) {
 }
 
 /**
- * Theme callback for displaying a preview of an image style.
+ * Returns HTML for a preview of an image style.
  *
  * @param $variables
  *   An associative array containing:
@@ -809,11 +809,11 @@ function theme_image_style_preview($variables) {
 }
 
 /**
- * Theme callback for displaying a grid of checkboxes.
+ * Returns HTML for a 3x3 grid of checkboxes for image anchors.
  *
  * @param $variables
  *   An associative array containing:
- *   - element: A Form API element containing radio buttons.
+ *   - element: A render element containing radio buttons.
  *
  * @ingroup themeable
  */
@@ -836,7 +836,7 @@ function theme_image_anchor($variables) {
 }
 
 /**
- * Theme callback for image resize effect summary output.
+ * Returns HTML for a summary of an image resize effect.
  *
  * @param $variables
  *   An associative array containing:
@@ -856,7 +856,7 @@ function theme_image_resize_summary($variables) {
 }
 
 /**
- * Theme callback for image scale effect summary output.
+ * Returns HTML for a summary of an image scale effect.
  *
  * @param $variables
  *   An associative array containing:
@@ -870,7 +870,7 @@ function theme_image_scale_summary($variables) {
 }
 
 /**
- * Theme callback for image crop effect summary output.
+ * Returns HTML for a summary of an image crop effect.
  *
  * @param $variables
  *   An associative array containing:
@@ -883,7 +883,7 @@ function theme_image_crop_summary($variables) {
 }
 
 /**
- * Theme callback for image rotate effect summary output.
+ * Returns HTML for a summary of an image rotate effect.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/image/image.field.inc modules/image/image.field.inc
index ce27380..387e18c 100644
--- modules/image/image.field.inc
+++ modules/image/image.field.inc
@@ -390,7 +390,13 @@ function image_field_widget_process($element, &$form_state, $form) {
 }
 
 /**
- * Theme the display of the image field widget.
+ * Returns HTML for an image field widget.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the image field widget.
+ *
+ * @ingroup themeable
  */
 function theme_image_widget($variables) {
   $element = $variables['element'];
@@ -490,7 +496,15 @@ function image_field_formatter_view($entity_type, $entity, $field, $instance, $l
 }
 
 /**
- * Theme function for image field formatters.
+ * Returns HTML for an image field formatter.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - item: An array of image data.
+ *   - image_style: An optional image style.
+ *   - path: An array containing the link 'path' and link 'options'.
+ *
+ * @ingroup themeable
  */
 function theme_image_formatter($variables) {
   $item = $variables['item'];
diff --git modules/image/image.module modules/image/image.module
index 5c319e4..85fb164 100644
--- modules/image/image.module
+++ modules/image/image.module
@@ -1010,7 +1010,7 @@ function image_effect_apply($image, $effect) {
 }
 
 /**
- * Return a themed image using a specific image style.
+ * Returns HTML for an image using a specific image style.
  *
  * @param $variables
  *   An associative array containing:
@@ -1025,8 +1025,6 @@ function image_effect_apply($image, $effect) {
  *   - getsize: If set to TRUE, the image's dimension are fetched and added as
  *     width/height attributes.
  *
- * @return
- *   A string containing the image tag.
  * @ingroup themeable
  */
 function theme_image_style($variables) {
diff --git modules/locale/locale.admin.inc modules/locale/locale.admin.inc
index 7676515..dee5b9a 100644
--- modules/locale/locale.admin.inc
+++ modules/locale/locale.admin.inc
@@ -51,14 +51,11 @@ function locale_languages_overview_form() {
 }
 
 /**
- * Theme the language overview form.
+ * Returns HTML for the language overview form.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: @todo: document
- *
- * @return
- *   A themed HTML string representing the form.
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -569,7 +566,11 @@ function _locale_languages_configure_form_language_table(&$form, $type) {
 }
 
 /**
- * Theme the language configure form.
+ * Returns HTML for a language configuration form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -1278,7 +1279,11 @@ function locale_translate_delete_form_submit($form, &$form_state) {
  */
 
 /**
- * Theme locale date format form.
+ * Returns HTML for a locale date format form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/menu/menu.admin.inc modules/menu/menu.admin.inc
index 71f671a..e033c0a 100644
--- modules/menu/menu.admin.inc
+++ modules/menu/menu.admin.inc
@@ -25,7 +25,14 @@ function menu_overview_page() {
 }
 
 /**
- * Theme the menu title and description for admin page
+ * Returns HTML for a menu title and description for the menu overview page.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - title: The menu's title.
+ *   - description: The menu's description.
+ *
+ * @ingroup themeable
  */
 function theme_menu_admin_overview($variables) {
   $output = check_plain($variables['title']);
@@ -177,7 +184,11 @@ function menu_overview_form_submit($form, &$form_state) {
 }
 
 /**
- * Theme the menu overview form into a table.
+ * Returns HTML for the menu overview form into a table.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/node/content_types.inc modules/node/content_types.inc
index b1f7edc..57bcec9 100644
--- modules/node/content_types.inc
+++ modules/node/content_types.inc
@@ -54,6 +54,17 @@ function node_overview_types() {
   return $build;
 }
 
+/**
+ * Returns HTML for a node type description for the content type admin overview page.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - name: The human-readable name of the content type.
+ *   - type: An object containing the 'type' (machine name) and 'description' of
+ *     the content type.
+ *
+ * @ingroup themeable
+ */
 function theme_node_admin_overview($variables) {
   $name = $variables['name'];
   $type = $variables['type'];
diff --git modules/node/node.admin.inc modules/node/node.admin.inc
index 906f781..0cce04f 100644
--- modules/node/node.admin.inc
+++ modules/node/node.admin.inc
@@ -204,7 +204,11 @@ function node_filter_form() {
 }
 
 /**
- * Theme node administration filter selector.
+ * Returns HTML for a node administration filter selector.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/node/node.module modules/node/node.module
index 410acc8..b2c4b3a 100644
--- modules/node/node.module
+++ modules/node/node.module
@@ -1406,7 +1406,11 @@ function template_preprocess_node(&$variables) {
 }
 
 /**
- * Theme a log message.
+ * Returns HTML for a log message.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - log: A node revision log.
  *
  * @ingroup themeable
  */
@@ -1707,7 +1711,11 @@ function node_user_delete($account) {
 }
 
 /**
- * Theme the content ranking part of the search settings admin page.
+ * Returns HTML for the content ranking part of the search settings admin page.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -2141,10 +2149,12 @@ function node_get_recent($number = 10) {
 }
 
 /**
- * Returns a formatted list of recent nodes.
+ * Returns HTML for a list of recent content.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - nodes: An array of recent node objects.
  *
- * @return
- *   The recent content table HTML.
  * @ingroup themeable
  */
 function theme_node_recent_block($variables) {
@@ -2180,10 +2190,12 @@ function theme_node_recent_block($variables) {
 }
 
 /**
- * Returns a formatted recent node to be displayed in the recent content block.
+ * Returns HTML for a recent node to be displayed in the recent content block.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - node: A node object.
  *
- * @return
- *   The recent content node's HTML.
  * @ingroup themeable
  */
 function theme_node_recent_content($variables) {
diff --git modules/node/node.pages.inc modules/node/node.pages.inc
index 4533bb1..82a14fb 100644
--- modules/node/node.pages.inc
+++ modules/node/node.pages.inc
@@ -28,7 +28,11 @@ function node_add_page() {
 }
 
 /**
- * Display the list of available node types for node creation.
+ * Returns HTML for a list of available node types for node creation.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - content: An array of content types.
  *
  * @ingroup themeable
  */
@@ -340,7 +344,7 @@ function node_preview($node) {
 }
 
 /**
- * Display a node preview for display during node creation and editing.
+ * Returns HTML for a node preview for display during node creation and editing.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/node/node.tpl.php modules/node/node.tpl.php
index 19b5f0c..cf74224 100644
--- modules/node/node.tpl.php
+++ modules/node/node.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a node.
+ * HTML for a node.
  *
  * Available variables:
  * - $title: the (sanitized) title of the node.
@@ -75,6 +75,7 @@
  * @see template_preprocess()
  * @see template_preprocess_node()
  * @see template_process()
+ * @ingroup themeable
  */
 ?>
 <div id="node-<?php print $node->nid; ?>" class="<?php print $classes; ?> clearfix"<?php print $attributes; ?>>
diff --git modules/poll/poll-bar--block.tpl.php modules/poll/poll-bar--block.tpl.php
index b67fa6e..331daa8 100644
--- modules/poll/poll-bar--block.tpl.php
+++ modules/poll/poll-bar--block.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display the bar for a single choice in a
- * poll.
+ * HTML for the results bar for a single choice in a poll when displayed in a block.
  *
  * Variables available:
  * - $title: The title of the poll.
@@ -15,6 +14,7 @@
  * - $voted: Set to TRUE if the user voted for this choice.
  *
  * @see template_preprocess_poll_bar()
+ * @ingroup themeable
  */
 ?>
 
diff --git modules/poll/poll-bar.tpl.php modules/poll/poll-bar.tpl.php
index 0345b95..239167f 100644
--- modules/poll/poll-bar.tpl.php
+++ modules/poll/poll-bar.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display the bar for a single choice in a
- * poll.
+ * HTML for the results bar for a single choice in a poll.
  *
  * Variables available:
  * - $title: The title of the poll.
@@ -15,6 +14,7 @@
  * - $voted: Set to TRUE if the user voted for this choice.
  *
  * @see template_preprocess_poll_bar()
+ * @ingroup themeable
  */
 ?>
 
diff --git modules/poll/poll-results--block.tpl.php modules/poll/poll-results--block.tpl.php
index bf2babd..db86312 100644
--- modules/poll/poll-results--block.tpl.php
+++ modules/poll/poll-results--block.tpl.php
@@ -2,7 +2,7 @@
 // $Id: poll-results--block.tpl.php,v 1.1 2010/01/13 06:07:27 webchick Exp $
 /**
  * @file
- * Default theme implementation to display the poll results in a block.
+ * HTML for poll results when displayed in a block.
  *
  * Variables available:
  * - $title: The title of the poll.
@@ -16,6 +16,7 @@
  * - $vote: The choice number of the current user's vote.
  *
  * @see template_preprocess_poll_results()
+ * @ingroup themeable
  */
 ?>
 
diff --git modules/poll/poll-results.tpl.php modules/poll/poll-results.tpl.php
index c894f7f..168ee59 100644
--- modules/poll/poll-results.tpl.php
+++ modules/poll/poll-results.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display the poll results in a block.
+ * HTML for poll results.
  *
  * Variables available:
  * - $title: The title of the poll.
@@ -16,6 +16,7 @@
  * - $vote: The choice number of the current user's vote.
  *
  * @see template_preprocess_poll_results()
+ * @ingroup themeable
  */
 ?>
 <div class="poll">
diff --git modules/poll/poll-vote.tpl.php modules/poll/poll-vote.tpl.php
index 8aacc13..4c7c80b 100644
--- modules/poll/poll-vote.tpl.php
+++ modules/poll/poll-vote.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display voting form for a poll.
+ * HTML for a voting form for a poll.
  *
  * - $choice: The radio buttons for the choices in the poll.
  * - $title: The title of the poll.
@@ -13,6 +13,7 @@
  *   form_alter hooks.
  *
  * @see template_preprocess_poll_vote()
+ * @ingroup themeable
  */
 ?>
 <div class="poll">
diff --git modules/poll/poll.module modules/poll/poll.module
index 90338bf..0555986 100644
--- modules/poll/poll.module
+++ modules/poll/poll.module
@@ -779,7 +779,11 @@ function poll_view_results($node, $view_mode, $block = FALSE) {
 
 
 /**
- * Theme the admin poll form for choices.
+ * Returns HTML for an admin poll form for choices.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/profile/profile-block.tpl.php modules/profile/profile-block.tpl.php
index d40356a..49e9b6d 100644
--- modules/profile/profile-block.tpl.php
+++ modules/profile/profile-block.tpl.php
@@ -3,8 +3,9 @@
 
 /**
  * @file
- * Default theme implementation for displaying a users profile within a
- * block. It only shows in relation to a node displayed as a full page.
+ * HTML for a users profile within a block.
+ *
+ * This template is only shown in relation to a node displayed as a full page.
  *
  * Available variables:
  * - $user_picture: Image configured for the account linking to the users page.
@@ -28,6 +29,7 @@
  *  <?php endif; ?>
  *
  * @see template_preprocess_profile_block()
+ * @ingroup themeable
  */
 ?>
 <?php print $user_picture; ?>
diff --git modules/profile/profile-listing.tpl.php modules/profile/profile-listing.tpl.php
index 7bced7d..3494708 100644
--- modules/profile/profile-listing.tpl.php
+++ modules/profile/profile-listing.tpl.php
@@ -3,11 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for displaying a user and their profile data
- * for member listing pages.
- *
- * @see profile-wrapper.tpl.php
- *      where all the data is collected and printed out.
+ * HTML for a user and their profile data for member listing pages.
  *
  * Available variables:
  * - $account: User's account object.
@@ -34,7 +30,10 @@
  *    </div>
  *  <?php endif; ?>
  *
+ * @see profile-wrapper.tpl.php
+ *      where all the data is collected and printed out.
  * @see template_preprocess_profile_listing()
+ * @ingroup themeable
  */
 ?>
 <div class="profile clearfix">
diff --git modules/profile/profile-wrapper.tpl.php modules/profile/profile-wrapper.tpl.php
index 4b9d3dd..b99e560 100644
--- modules/profile/profile-wrapper.tpl.php
+++ modules/profile/profile-wrapper.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for wrapping member listings and their
- * profiles.
+ * HTML for a wrapper for member listings and their profiles.
  *
  * This template is used when viewing a list of users. It can be a general
  * list for viewing all users with the url of "example.com/profile" or when
@@ -18,6 +17,7 @@
  *   is also based on this, e.g., "profile-wrapper-last_name.tpl.php".
  *
  * @see template_preprocess_profile_wrapper()
+ * @ingroup themeable
  */
 ?>
 <div id="profile">
diff --git modules/profile/profile.admin.inc modules/profile/profile.admin.inc
index b2d765a..e5a83c6 100644
--- modules/profile/profile.admin.inc
+++ modules/profile/profile.admin.inc
@@ -91,10 +91,14 @@ function profile_admin_overview_submit($form, &$form_state) {
 }
 
 /**
- * Theme the profile field overview into a drag and drop enabled table.
+ * Returns HTML for the profile field overview form into a drag and drop enabled table.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
- * @ingroup themeable
  * @see profile_admin_overview()
+ * @ingroup themeable
  */
 function theme_profile_admin_overview($variables) {
   $form = $variables['form'];
diff --git modules/rdf/rdf.module modules/rdf/rdf.module
index dc8a990..7a2bb9d 100644
--- modules/rdf/rdf.module
+++ modules/rdf/rdf.module
@@ -721,7 +721,7 @@ function rdf_preprocess_image(&$variables) {
 }
 
 /**
- * Wraps a template variable in an HTML element with the desired attributes.
+ * Returns HTML for a template variable wrapped in an HTML element with the desired attributes.
  *
  * This is called by rdf_process() shortly before the theme system renders
  * a template file. It is called once for each template variable for which
@@ -732,6 +732,14 @@ function rdf_preprocess_image(&$variables) {
  * that need containing attributes are routed through this function, allowing
  * the template file to receive properly wrapped variables.
  *
+ * Tip for themers: if you're already outputting a wrapper element around a
+ * particular template variable in your template file and if you don't want
+ * an extra wrapper element, you can override this function to not wrap that
+ * variable and instead print the following inside your template file:
+ * @code
+ *   drupal_attributes($rdf_template_variable_attributes_array[$variable_name])
+ * @endcode
+ *
  * @param $variables
  *   An associative array containing:
  *   - content: A string of content to be wrapped with attributes.
@@ -760,20 +768,7 @@ function rdf_preprocess_image(&$variables) {
  *     hook_preprocess_rdf_template_variable_wrapper() and set 'inline'
  *     accordingly.
  *
- * @return
- *   A string containing the wrapped content. The template receives the for its
- *   variable instead of the original content.
- *
- * Tip for themers: if you're already outputting a wrapper element around a
- * particular template variable in your template file and if you don't want
- * an extra wrapper element, you can override this function to not wrap that
- * variable and instead print the following inside your template file:
- * @code
- *   drupal_attributes($rdf_template_variable_attributes_array[$variable_name])
- * @endcode
- *
  * @see rdf_process()
- *
  * @ingroup themeable
  * @ingroup rdf
  */
@@ -787,7 +782,7 @@ function theme_rdf_template_variable_wrapper($variables) {
 }
 
 /**
- * Outputs a series of empty spans for exporting RDF metadata in RDFa.
+ * Returns HTML for a series of empty spans for exporting RDF metadata in RDFa.
  *
  * Sometimes it is useful to export data which is not semantically present in
  * the HTML output. For example, a hierarchy of comments is visible for a human
@@ -801,11 +796,7 @@ function theme_rdf_template_variable_wrapper($variables) {
  *     corresponds to its own set of attributes, and therefore, needs its own
  *     element.
  *
- * @return
- *   A string of HTML containing markup that can be understood by RDFa parsers.
- *
  * @see rdf_process()
- *
  * @ingroup themeable
  * @ingroup rdf
  */
diff --git modules/search/search-block-form.tpl.php modules/search/search-block-form.tpl.php
index fe8a6f3..e918335 100644
--- modules/search/search-block-form.tpl.php
+++ modules/search/search-block-form.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for displaying a search form within a block
- * region.
+ * HTML for a search form within a block.
  *
  * Available variables:
  * - $search_form: The complete search form ready for print.
@@ -31,6 +30,7 @@
  *   <?php print '<pre>'. check_plain(print_r($search, 1)) .'</pre>'; ?>
  *
  * @see template_preprocess_search_block_form()
+ * @ingroup themeable
  */
 ?>
 <div class="container-inline">
diff --git modules/search/search-result.tpl.php modules/search/search-result.tpl.php
index 021437b..d3c59de 100644
--- modules/search/search-result.tpl.php
+++ modules/search/search-result.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for displaying a single search result.
+ * HTML for a single search result.
  *
  * This template renders a single search result and is collected into
  * search-results.tpl.php. This and the parent template are
@@ -44,6 +44,7 @@
  *   <?php print '<pre>'. check_plain(print_r($info_split, 1)) .'</pre>'; ?>
  *
  * @see template_preprocess_search_result()
+ * @ingroup themeable
  */
 ?>
 <dt class="title">
diff --git modules/search/search-results.tpl.php modules/search/search-results.tpl.php
index 48e17d7..24c24f2 100644
--- modules/search/search-results.tpl.php
+++ modules/search/search-results.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation for displaying search results.
+ * HTML for search results.
  *
  * This template collects each invocation of theme_search_result(). This and
  * the child template are dependent to one another sharing the markup for
@@ -19,6 +19,7 @@
  *
  *
  * @see template_preprocess_search_results()
+ * @ingroup themeable
  */
 ?>
 <?php if ($search_results) : ?>
diff --git modules/search/search.pages.inc modules/search/search.pages.inc
index b7f6ba2..cbc52dc 100644
--- modules/search/search.pages.inc
+++ modules/search/search.pages.inc
@@ -47,15 +47,14 @@ function search_view($type = 'node') {
 }
 
 /**
- * Theme the listing of search results
+ * Returns HTML for a listing of search results.
  *
  * @param $variables
  *   An associative array containing:
  *   - title: The subject of the listing.
  *   - content: The content of the listing.
  *
- * @return
- *   A string containing the listing output.
+ * @ingroup themeable
  */
 function theme_search_results_listing($variables) {
   $output = '<h2 class="title">' . $variables['title'] . '</h2><div>' . $variables['content'] . '</div>';
diff --git modules/shortcut/shortcut.admin.inc modules/shortcut/shortcut.admin.inc
index 926eafe..c098225 100644
--- modules/shortcut/shortcut.admin.inc
+++ modules/shortcut/shortcut.admin.inc
@@ -294,17 +294,14 @@ function shortcut_set_customize_submit($form, &$form_state) {
 }
 
 /**
- * Themes the shortcut set customization form.
+ * Returns HTML for a shortcut set customization form.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An array representing the form.
+ *   - form: A render element representing the form.
  *
- * @return
- *   A themed HTML string representing the content of the form.
- *
- * @ingroup themeable
  * @see shortcut_set_customize()
+ * @ingroup themeable
  */
 function theme_shortcut_set_customize($variables) {
   $form = $variables['form'];
diff --git modules/simpletest/simpletest.pages.inc modules/simpletest/simpletest.pages.inc
index 9172d1c..943ae24 100644
--- modules/simpletest/simpletest.pages.inc
+++ modules/simpletest/simpletest.pages.inc
@@ -58,14 +58,13 @@ function simpletest_test_form($form) {
 }
 
 /**
- * Theme the test list generated by simpletest_test_form() into a table.
+ * Returns HTML for a test list generated by simpletest_test_form() into a table.
  *
  * @param $variables
  *   An associative array containing:
- *   - table: Form array that represent a table.
+ *   - table: A render element representing the table.
  *
- * @return
- *   HTML output.
+ * @ingroup themeable
  */
 function theme_simpletest_test_table($variables) {
   $table = $variables['table'];
@@ -366,9 +365,13 @@ function simpletest_result_form_submit($form, &$form_state) {
 }
 
 /**
- * Add wrapper div with class based on summary status.
+ * Returns HTML for the summary status of a simpletest result.
  *
- * @return HTML output.
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
+ *
+ * @ingroup themeable
  */
 function theme_simpletest_result_summary($variables) {
   $form = $variables['form'];
diff --git modules/syslog/syslog.module modules/syslog/syslog.module
index 4279c03..548cad0 100644
--- modules/syslog/syslog.module
+++ modules/syslog/syslog.module
@@ -95,7 +95,20 @@ function syslog_theme() {
 }
 
 /**
- * Format a system log entry.
+ * Returns a string for a system log entry.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - entry: An array containing the data about the log entry, containing:
+ *     - timestamp: The date and time of the log entry.
+ *     - type: The type of log entry.
+ *     - ip: The IP address.
+ *     - request_uri: The requested URI.
+ *     - referer: The URL which referred to the request URI.
+ *     - user: The user object associated with the log entry.
+ *     - link: A link accociated with the log entry.
+ *     - variables: A string representing the data to log.
+ *     - message: If variables is not specified, a string for the log message.
  *
  * @ingroup themeable
  */
diff --git modules/system/html.tpl.php modules/system/html.tpl.php
index 988b4b6..3321b72 100644
--- modules/system/html.tpl.php
+++ modules/system/html.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display the basic html structure of a single
- * Drupal page.
+ * HTML for the basic html structure of a single Drupal page.
  *
  * Variables:
  * - $css: An array of CSS files for the current page.
@@ -32,6 +31,7 @@
  * @see template_preprocess()
  * @see template_preprocess_html()
  * @see template_process()
+ * @ingroup themeable
  */
 ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.0//EN"
   "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-1.dtd">
diff --git modules/system/maintenance-page.tpl.php modules/system/maintenance-page.tpl.php
index 84a57da..104660a 100644
--- modules/system/maintenance-page.tpl.php
+++ modules/system/maintenance-page.tpl.php
@@ -3,13 +3,14 @@
 
 /**
  * @file
- * Default theme implementation to display a single Drupal page while offline.
+ * HTML for a single Drupal page while offline.
  *
  * All the available variables are mirrored in page.tpl.php. Some may be left
  * blank but they are provided for consistency.
  *
  * @see template_preprocess()
  * @see template_preprocess_maintenance_page()
+ * @ingroup themeable
  */
 ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
diff --git modules/system/page.tpl.php modules/system/page.tpl.php
index f97b34c..cb8b2c3 100644
--- modules/system/page.tpl.php
+++ modules/system/page.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a single Drupal page.
+ * HTML for a single Drupal page.
  *
  * Available variables:
  *
@@ -65,6 +65,7 @@
  * @see template_preprocess()
  * @see template_preprocess_page()
  * @see template_process()
+ * @ingroup themeable
  */
 ?>
 
diff --git modules/system/region.tpl.php modules/system/region.tpl.php
index adb164a..a1e7733 100644
--- modules/system/region.tpl.php
+++ modules/system/region.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a region.
+ * HTML for a page region.
  *
  * Available variables:
  * - $content: The content for this region, typically blocks.
@@ -25,6 +25,7 @@
  * @see template_preprocess()
  * @see template_preprocess_region()
  * @see template_process()
+ * @ingroup themeable
  */
 ?>
 <div class="<?php print $classes; ?>">
diff --git modules/system/system.admin.inc modules/system/system.admin.inc
index daa917d..27a7e67 100644
--- modules/system/system.admin.inc
+++ modules/system/system.admin.inc
@@ -1982,7 +1982,11 @@ function system_date_time_settings() {
 }
 
 /**
- * Theme function for date settings form.
+ * Returns HTML for the date settings form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -2270,12 +2274,12 @@ function system_batch_page() {
 }
 
 /**
- * This function formats an administrative block for display.
+ * Returns HTML for an administrative block for display.
  *
  * @param $variables
  *   An associative array containing:
- *   - block: An array containing information about the block. It should
- *     include a 'title', a 'description' and a formatted 'content'.
+ *   - block: An array containing information about the block. It should include
+ *     a 'title', a 'description' and a formatted 'content'.
  *
  * @ingroup themeable
  */
@@ -2315,7 +2319,7 @@ EOT;
 }
 
 /**
- * This function formats the content of an administrative block.
+ * Returns HTML for the content of an administrative block.
  *
  * @param $variables
  *   An associative array containing:
@@ -2350,14 +2354,14 @@ function theme_admin_block_content($variables) {
 }
 
 /**
- * This function formats an administrative page for viewing.
+ * Returns HTML for an administrative page.
  *
  * @param $variables
  *   An associative array containing:
  *   - blocks: An array of blocks to display. Each array should include a
- *     'title', a 'description', a formatted 'content' and a
- *     'position' which will control which container it will be
- *     in. This is usually 'left' or 'right'.
+ *     'title', a 'description', a formatted 'content' and a 'position' which
+ *     will control which container it will be in. This is usually 'left' or
+ *     'right'.
  *
  * @ingroup themeable
  */
@@ -2393,7 +2397,7 @@ function theme_admin_page($variables) {
 }
 
 /**
- * Theme output of the dashboard page.
+ * Returns HTML for the output of the dashboard page.
  *
  * @param $variables
  *   An associative array containing:
@@ -2445,7 +2449,7 @@ function theme_system_admin_by_module($variables) {
 }
 
 /**
- * Theme requirements status report.
+ * Returns HTML for the status report.
  *
  * @param $variables
  *   An associative array containing:
@@ -2486,11 +2490,11 @@ function theme_status_report($variables) {
 }
 
 /**
- * Theme callback for the modules form.
+ * Returns HTML for the modules form.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An associative array containing the structure of the form.
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -2533,32 +2537,26 @@ function theme_system_modules_fieldset($variables) {
 }
 
 /**
- * Themes an incompatible message.
- *
- * @ingroup themeable
+ * Returns HTML for a message about incompatible modules.
  *
  * @param $variables
  *   An associative array containing:
  *   - message: The form array representing the currently disabled modules.
  *
- * @return
- *   An HTML string for the message.
+ * @ingroup themeable
  */
 function theme_system_modules_incompatible($variables) {
   return '<div class="incompatible">' . $variables['message'] . '</div>';
 }
 
 /**
- * Themes a table of currently disabled modules.
- *
- * @ingroup themeable
+ * Returns HTML for a table of currently disabled modules.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: The form array representing the currently disabled modules.
+ *   - form: A render element representing the form.
  *
- * @return
- *   An HTML string representing the table.
+ * @ingroup themeable
  */
 function theme_system_modules_uninstall($variables) {
   $form = $variables['form'];
@@ -2591,7 +2589,7 @@ function theme_system_modules_uninstall($variables) {
 }
 
 /**
- * Theme function for the system themes form.
+ * Returns HTML for the Appearance page.
  *
  * @param $variables
  *   An associative array containing:
diff --git modules/system/system.module modules/system/system.module
index c2cb095..dcc34c8 100644
--- modules/system/system.module
+++ modules/system/system.module
@@ -3138,16 +3138,16 @@ function system_timezone($abbreviation = '', $offset = -1, $is_daylight_saving_t
 }
 
 /**
- * Format the Powered by Drupal text.
+ * Returns HTML for the Powered by Drupal text.
  *
  * @ingroup themeable
  */
-function theme_system_powered_by($variables) {
+function theme_system_powered_by() {
   return '<span>' . t('Powered by <a href="@poweredby">Drupal</a>', array('@poweredby' => 'http://drupal.org')) . '</span>';
 }
 
 /**
- * Display the link to show or hide inline help descriptions.
+ * Returns HTML for a link to show or hide inline help descriptions.
  *
  * @ingroup themeable
  */
@@ -3627,14 +3627,15 @@ function system_archiver_info() {
 }
 
 /**
- * Theme confirmation forms.
+ * Returns HTML for a confirmation form.
  *
  * By default this does not alter the appearance of a form at all,
  * but is provided as a convenience for themers.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An associative array containing the structure of the form.
+ *   - form: A render element representing the form.
+ *
  * @ingroup themeable
  */
 function theme_confirm_form($variables) {
@@ -3642,14 +3643,15 @@ function theme_confirm_form($variables) {
 }
 
 /**
- * Theme function for the system settings form.
+ * Returns HTML for a system settings form.
  *
  * By default this does not alter the appearance of a form at all,
  * but is provided as a convenience for themers.
  *
  * @param $variables
  *   An associative array containing:
- *   - form: An associative array containing the structure of the form.
+ *   - form: A render element representing the form.
+ *
  * @ingroup themeable
  */
 function theme_system_settings_form($variables) {
diff --git modules/system/theme.api.php modules/system/theme.api.php
index d0d85e8..eaf9d67 100644
--- modules/system/theme.api.php
+++ modules/system/theme.api.php
@@ -2,70 +2,46 @@
 // $Id: theme.api.php,v 1.1 2010/02/27 09:24:09 dries Exp $
 
 /**
- * @defgroup themeable Default theme implementations
+ * @defgroup themeable Theming hooks
  * @{
- * Functions and templates that present output to the user, and can be
- * implemented by themes.
+ * Functions and templates that return string output (usually HTML) to the user
+ * and can be overridden by themes.
  *
- * Drupal's presentation layer is a pluggable system known as the theme
- * layer. Each theme can take control over most of Drupal's output, and
- * has complete control over the CSS.
+ * Drupal's presentation layer is a pluggable system known as the theme layer.
+ * Each module is responsible for providing the default theming for its data.
+ * But each theme can take control over all of Drupal's output, including HTML,
+ * JavaScript and CSS.
  *
- * Inside Drupal, the theme layer is utilized by the use of the theme()
- * function, which is passed the name of a component (the theme hook)
- * and an array of variables. For example,
- * theme('table', array('header' => $header, 'rows' => $rows));
- * Additionally, the theme() function can take an array of theme
- * hooks, which can be used to provide 'fallback' implementations to
- * allow for more specific control of output. For example, the function:
- * theme(array('table__foo', 'table'), $variables) would look to see if
- * 'table__foo' is registered anywhere; if it is not, it would 'fall back'
- * to the generic 'table' implementation. This can be used to attach specific
- * theme functions to named objects, allowing the themer more control over
- * specific types of output.
+ * Inside Drupal, the theme layer is controlled by the use of the theme()
+ * function, which is passed the name of the theming hook and an array of
+ * variables. For example, theme('table', array('header' => $header, 'rows' =>
+ * $rows)); For more information, see the documentation for theme().
  *
- * As of Drupal 6, every theme hook is required to be registered by the
- * module that owns it, so that Drupal can tell what to do with it and
- * to make it simple for themes to identify and override the behavior
- * for these calls.
- *
- * The theme hooks are registered via hook_theme(), which returns an
+ * Every theming hook is required to be registered by the module that owns it.
+ * The theming hooks are registered via hook_theme(), which returns an
  * array of arrays with information about the hook. It describes the
- * arguments the function or template will need, and provides
- * defaults for the template in case they are not filled in. If the default
- * implementation is a function, by convention it is named theme_HOOK().
- *
- * Each module should provide a default implementation for theme_hooks that
- * it registers. This implementation may be either a function or a template;
- * if it is a function it must be specified via hook_theme(). By convention,
- * default implementations of theme hooks are named theme_HOOK. Default
- * template implementations are stored in the module directory.
+ * variables (or render element) the function or template will need, and
+ * provides the variable defaults for the template in case they are not
+ * specified when the theming hook is called.
  *
- * Drupal's default template renderer is a simple PHP parsing engine that
- * includes the template and stores the output. Drupal's theme engines
- * can provide alternate template engines, such as XTemplate, Smarty and
- * PHPTal. The most common template engine is PHPTemplate (included with
- * Drupal and implemented in phptemplate.engine, which uses Drupal's default
- * template renderer.
+ * Each module must provide a default implementation for themeing hooks that
+ * it registers. This implementation may be either a function or a template. By
+ * convention, default implementations of theming hooks are named theme_HOOK().
+ * Default template implementations are stored in the module's directory and are
+ * named HOOK.tpl.php.
  *
- * In order to create theme-specific implementations of these hooks, themes can
- * implement their own version of theme hooks, either as functions or templates.
- * These implementations will be used instead of the default implementation. If
- * using a pure .theme without an engine, the .theme is required to implement
- * its own version of hook_theme() to tell Drupal what it is implementing;
- * themes utilizing an engine will have their well-named theming functions
- * automatically registered for them. While this can vary based upon the theme
- * engine, the standard set by phptemplate is that theme functions should be
+ * Themes can implement their own version of theming hooks, either as functions
+ * or templates. These implementations will be used instead of the
+ * module-provided default implementation. Templates implemented by themes
+ * should be named the same as the original template. Theme functions should be
  * named THEMENAME_HOOK. For example, for Drupal's default theme (Garland) to
- * implement the 'table' hook, the phptemplate.engine would find
- * garland_table().
- *
- * The theme system is described and defined in theme.inc.
+ * implement the 'table' hook, it would need to create a garland_table()
+ * function.
  *
  * @see theme()
  * @see hook_theme()
  *
- * @} End of "defgroup themeable".
+ * @}
  */
 
 /**
diff --git modules/taxonomy/taxonomy-term.tpl.php modules/taxonomy/taxonomy-term.tpl.php
index ec19b36..7edba69 100644
--- modules/taxonomy/taxonomy-term.tpl.php
+++ modules/taxonomy/taxonomy-term.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to display a term.
+ * HTML for a taxonomy term.
  *
  * Available variables:
  * - $name: the (sanitized) name of the term.
@@ -36,6 +36,7 @@
  * @see template_preprocess()
  * @see template_preprocess_taxonomy_term()
  * @see template_process()
+ * @ingroup themeable
  */
 ?>
 <div id="taxonomy-term-<?php print $term->tid; ?>" class="<?php print $classes; ?> clearfix">
diff --git modules/taxonomy/taxonomy.admin.inc modules/taxonomy/taxonomy.admin.inc
index 902c67c..0349d22 100644
--- modules/taxonomy/taxonomy.admin.inc
+++ modules/taxonomy/taxonomy.admin.inc
@@ -52,10 +52,14 @@ function taxonomy_overview_vocabularies_submit($form, &$form_state) {
 }
 
 /**
- * Theme the vocabulary overview as a sortable list of vocabularies.
+ * Returns HTML for the vocabulary overview form as a sortable list of vocabularies.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
- * @ingroup themeable
  * @see taxonomy_overview_vocabularies()
+ * @ingroup themeable
  */
 function theme_taxonomy_overview_vocabularies($variables) {
   $form = $variables['form'];
@@ -513,10 +517,14 @@ function taxonomy_overview_terms_submit($form, &$form_state) {
 }
 
 /**
- * Theme the terms overview as a sortable list of terms.
+ * Returns HTML for a terms overview form as a sortable list of terms.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
- * @ingroup themeable
  * @see taxonomy_overview_terms()
+ * @ingroup themeable
  */
 function theme_taxonomy_overview_terms($variables) {
   $form = $variables['form'];
diff --git modules/toolbar/toolbar.tpl.php modules/toolbar/toolbar.tpl.php
index 951a5f0..10a9f61 100644
--- modules/toolbar/toolbar.tpl.php
+++ modules/toolbar/toolbar.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default template for admin toolbar.
+ * HTML for the admin toolbar.
  *
  * Available variables:
  * - $classes: String of classes that can be used to style contextually through
@@ -20,6 +20,7 @@
  *
  * @see template_preprocess()
  * @see template_preprocess_toolbar()
+ * @ingroup themeable
  */
 ?>
 <div id="toolbar" class="<?php print $classes; ?> clearfix">
diff --git modules/trigger/trigger.admin.inc modules/trigger/trigger.admin.inc
index 1b68567..79a2d47 100644
--- modules/trigger/trigger.admin.inc
+++ modules/trigger/trigger.admin.inc
@@ -272,15 +272,12 @@ function trigger_assign_form_submit($form, &$form_state) {
 }
 
 /**
- * Displays actions assigned to this hook in a table.
+ * Returns HTML for the form showing actions assigned to a trigger.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: The fieldset including all assigned actions.
  *
- * @return
- *   The rendered form with the table prepended.
- *
  * @ingroup themeable
  */
 function theme_trigger_display($variables) {
diff --git modules/update/update.manager.inc modules/update/update.manager.inc
index a8ddd88..137c888 100644
--- modules/update/update.manager.inc
+++ modules/update/update.manager.inc
@@ -256,10 +256,11 @@ function update_manager_update_form($form, $form_state = array(), $context) {
 }
 
 /**
- * Theme the first page in the update manager wizard to select projects.
+ * Returns HTML for the first page in the update manager wizard to select projects.
  *
  * @param $variables
- *   form: The form
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/update/update.module modules/update/update.module
index 8bba6fe..2a62ec0 100644
--- modules/update/update.module
+++ modules/update/update.module
@@ -606,14 +606,15 @@ function _update_project_status_sort($a, $b) {
 }
 
 /**
- * Render the HTML to display the last time we checked for update data.
+ * Returns HTML for the last time we checked for update data.
  *
  * In addition to properly formating the given timestamp, this function also
  * provides a "Check manually" link that refreshes the available update and
  * redirects back to the same page.
  *
  * @param $variables
- *   'last': The timestamp when the site last checked for available updates.
+ *   An associative array containing:
+ *   - 'last': The timestamp when the site last checked for available updates.
  *
  * @see theme_update_report()
  * @see theme_update_available_updates_form()
diff --git modules/update/update.report.inc modules/update/update.report.inc
index d4b2a95..13804ec 100644
--- modules/update/update.report.inc
+++ modules/update/update.report.inc
@@ -21,7 +21,11 @@ function update_status() {
 }
 
 /**
- * Theme project status report.
+ * Returns HTML for the project status report.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - data: An array of data about each project's status.
  *
  * @ingroup themeable
  */
@@ -244,7 +248,7 @@ function theme_update_report($variables) {
 }
 
 /**
- * Generate the HTML for the label to display for a project's update status.
+ * Returns HTML for a label to display for a project's update status.
  *
  * @param $variables
  *   An associative array containing:
@@ -273,7 +277,17 @@ function theme_update_status_label($variables) {
 }
 
 /**
- * Theme the version display of a project.
+ * Returns HTML for the version display of a project.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - version: An array of data about the latest released version, containing:
+ *     - version: The version number.
+ *     - release_link: The URL for the release notes.
+ *     - date: The date of the release.
+ *     - download_link: The URL for the downloadable file.
+ *   - tag: The title of the project.
+ *   - class: A string containing extra classes for the wrapping table.
  *
  * @ingroup themeable
  */
diff --git modules/user/user-picture.tpl.php modules/user/user-picture.tpl.php
index 9d62c13..7578a06 100644
--- modules/user/user-picture.tpl.php
+++ modules/user/user-picture.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present an picture configured for the
- * user's account.
+ * HTML for a picture configured for the user's account.
  *
  * Available variables:
  * - $user_picture: Image set by the user or the site's default. Will be linked
@@ -13,6 +12,7 @@
  *   check_plain() before use.
  *
  * @see template_preprocess_user_picture()
+ * @ingroup themeable
  */
 ?>
 <?php if ($user_picture): ?>
diff --git modules/user/user-profile-category.tpl.php modules/user/user-profile-category.tpl.php
index 69145fc..fb40f96 100644
--- modules/user/user-profile-category.tpl.php
+++ modules/user/user-profile-category.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present profile categories (groups of
- * profile items).
+ * HTML for profile categories (groups of profile items).
  *
  * Categories are defined when configuring user profile fields for the site.
  * It can also be defined by modules. All profile items for a category will be
@@ -23,6 +22,7 @@
  * - $attributes: HTML attributes. Usually renders classes.
  *
  * @see template_preprocess_user_profile_category()
+ * @ingroup themeable
  */
 ?>
 <?php if ($title) : ?>
diff --git modules/user/user-profile-item.tpl.php modules/user/user-profile-item.tpl.php
index 2275c12..f9d2c10 100644
--- modules/user/user-profile-item.tpl.php
+++ modules/user/user-profile-item.tpl.php
@@ -3,8 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present profile items (values from user
- * account profile fields or modules).
+ * HTML for profile items (values from user account profile fields or modules).
  *
  * This template is used to loop through and render each field configured
  * for the user's account. It can also be the data from modules. The output is
@@ -21,6 +20,7 @@
  * - $attributes: HTML attributes. Usually renders classes.
  *
  * @see template_preprocess_user_profile_item()
+ * @ingroup themeable
  */
 ?>
 <dt<?php print $attributes; ?>><?php print $title; ?></dt>
diff --git modules/user/user-profile.tpl.php modules/user/user-profile.tpl.php
index f27aaf9..01522ba 100644
--- modules/user/user-profile.tpl.php
+++ modules/user/user-profile.tpl.php
@@ -3,7 +3,7 @@
 
 /**
  * @file
- * Default theme implementation to present all user profile data.
+ * HTML for all user profile data.
  *
  * This template is used when viewing a registered member's profile page,
  * e.g., example.com/user/123. 123 being the users ID.
@@ -31,6 +31,7 @@
  * @see user-profile-item.tpl.php
  *   Where the html is handled for each item in the group.
  * @see template_preprocess_user_profile()
+ * @ingroup themeable
  */
 ?>
 <div class="profile"<?php print $attributes; ?>>
diff --git modules/user/user.admin.inc modules/user/user.admin.inc
index fab19b6..d8664a3 100644
--- modules/user/user.admin.inc
+++ modules/user/user.admin.inc
@@ -733,7 +733,11 @@ function user_admin_permissions_submit($form, &$form_state) {
 }
 
 /**
- * Theme the administer permissions page.
+ * Returns HTML for the administer permissions page.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -770,7 +774,7 @@ function theme_user_admin_permissions($variables) {
 }
 
 /**
- * Theme an individual permission description.
+ * Returns HTML for an individual permission description.
  *
  * @param $variables
  *   An associative array containing:
@@ -861,7 +865,11 @@ function user_admin_roles_order_submit($form, &$form_state) {
 }
 
 /**
- * Theme the role order and new role form.
+ * Returns HTML for the role order and new role form.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
@@ -1007,7 +1015,11 @@ function user_admin_role_delete_confirm_submit($form, &$form_state) {
 }
 
 /**
- * Theme user administration filter selector.
+ * Returns HTML for the user administration filter selector.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - form: A render element representing the form.
  *
  * @ingroup themeable
  */
diff --git modules/user/user.module modules/user/user.module
index c8d95eb..c18f4f7 100644
--- modules/user/user.module
+++ modules/user/user.module
@@ -1342,7 +1342,7 @@ function template_preprocess_user_picture(&$variables) {
 }
 
 /**
- * Make a list of users.
+ * Returns HTML for a list of users.
  *
  * @param $variables
  *   An associative array containing:
@@ -3116,7 +3116,11 @@ function user_comment_view($comment) {
 }
 
 /**
- * Theme output of user signature.
+ * Returns HTML for a user signature.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - signature: The user's signature.
  *
  * @ingroup themeable
  */