- Patch #716496 by JohnAlbin: documentation updates for theme functions.

5 files changed, 195 insertions, 301 deletions

diff --git a/includes/form.inc b/includes/form.inc
index 93d0304b6..fcadc3c36 100644
--- a/includes/form.inc
+++ b/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 a/includes/menu.inc b/includes/menu.inc
index 048980d03..4b5ca3aed 100644
--- a/includes/menu.inc
+++ b/includes/menu.inc
@@ -1372,24 +1372,20 @@ function _menu_tree_data(&$links, $parents, $depth) {
 }
 
 /**
- * Preprocess the rendered tree for theme_menu_tree.
- *
- * @ingroup themeable
+ * Preprocesses the rendered tree for 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 +1393,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 +1413,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 +1445,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 a/includes/pager.inc b/includes/pager.inc
index 7430cfe8c..a33087c64 100644
--- a/includes/pager.inc
+++ b/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 a/includes/theme.inc b/includes/theme.inc
index 2e5c691bd..6bfb95c40 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -1329,8 +1329,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 +1339,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 +1370,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 +1382,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 +1392,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 +1422,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 +1500,7 @@ function theme_links($variables) {
 }
 
 /**
- * Return a themed image.
+ * Returns HTML for an image.
  *
  * @param $variables
  *   An associative array containing:
@@ -1521,9 +1512,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 +1528,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 +1548,7 @@ function theme_breadcrumb($variables) {
 }
 
 /**
- * Return a themed table.
+ * Returns HTML for a table.
  *
  * @param $variables
  *   An associative array containing:
@@ -1634,9 +1619,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 +1745,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 +1757,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 +1773,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 +1794,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 +1807,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 +1860,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 +1886,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 +1923,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 +1949,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 +1969,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 +1987,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 = '';
@@ -2583,3 +2472,80 @@ function template_preprocess_region(&$variables) {
   $variables['classes_array'][] = $region;
   $variables['theme_hook_suggestions'][] = 'region__' . $region;
 }
+
+/**
+ * Preprocesses 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 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'));
+}
+
+/**
+ * Processes variables for 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 a/includes/theme.maintenance.inc b/includes/theme.maintenance.inc
index c19dd05db..1a60911b1 100644
--- a/includes/theme.maintenance.inc
+++ b/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 = '';