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

42 files changed, 356 insertions, 192 deletions

diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module
index d7343050e..b6cf40c3b 100644
--- a/modules/aggregator/aggregator.module
+++ b/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 a/modules/aggregator/aggregator.pages.inc b/modules/aggregator/aggregator.pages.inc
index f8eb047af..1613a501a 100644
--- a/modules/aggregator/aggregator.pages.inc
+++ b/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,13 +369,15 @@ 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
  */
 function theme_aggregator_page_rss($variables) {
@@ -437,12 +437,14 @@ 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
  */
 function theme_aggregator_page_opml($variables) {
diff --git a/modules/book/book.admin.inc b/modules/book/book.admin.inc
index d185b0836..7a319430a 100644
--- a/modules/book/book.admin.inc
+++ b/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 a/modules/book/book.module b/modules/book/book.module
index 9d5938331..31401958f 100644
--- a/modules/book/book.module
+++ b/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 a/modules/color/color.module b/modules/color/color.module
index 04d8e9bb4..65cd33608 100644
--- a/modules/color/color.module
+++ b/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 a/modules/comment/comment.module b/modules/comment/comment.module
index 21c16949c..f9305e808 100644
--- a/modules/comment/comment.module
+++ b/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() {
@@ -2204,7 +2202,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 a/modules/dashboard/dashboard.module b/modules/dashboard/dashboard.module
index c90f65d75..1ef9ef195 100644
--- a/modules/dashboard/dashboard.module
+++ b/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 a/modules/dblog/dblog.admin.inc b/modules/dblog/dblog.admin.inc
index 4f344f577..1f5ba8833 100644
--- a/modules/dblog/dblog.admin.inc
+++ b/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 a/modules/field/field.form.inc b/modules/field/field.form.inc
index b5be9224c..5fd367a07 100644
--- a/modules/field/field.form.inc
+++ b/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 a/modules/field/field.module b/modules/field/field.module
index c3765cfaa..d470c9fd7 100644
--- a/modules/field/field.module
+++ b/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 a/modules/field/modules/options/options.module b/modules/field/modules/options/options.module
index 72a713afd..24ab04758 100644
--- a/modules/field/modules/options/options.module
+++ b/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 a/modules/file/file.field.inc b/modules/file/file.field.inc
index 57c47ae1e..ddd449e7e 100644
--- a/modules/file/file.field.inc
+++ b/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 a/modules/file/file.module b/modules/file/file.module
index b3153e647..b925d7c2e 100644
--- a/modules/file/file.module
+++ b/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 a/modules/filter/filter.admin.inc b/modules/filter/filter.admin.inc
index 257919344..5e6254c72 100644
--- a/modules/filter/filter.admin.inc
+++ b/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 a/modules/filter/filter.module b/modules/filter/filter.module
index a69d26031..29be14894 100644
--- a/modules/filter/filter.module
+++ b/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 a/modules/filter/filter.pages.inc b/modules/filter/filter.pages.inc
index ce3d842d3..e018e819d 100644
--- a/modules/filter/filter.pages.inc
+++ b/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 a/modules/forum/forum.admin.inc b/modules/forum/forum.admin.inc
index 49cb555ec..607089f66 100644
--- a/modules/forum/forum.admin.inc
+++ b/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 a/modules/image/image.admin.inc b/modules/image/image.admin.inc
index 3ca88d5cf..8ef98a84a 100644
--- a/modules/image/image.admin.inc
+++ b/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 a/modules/image/image.field.inc b/modules/image/image.field.inc
index 20c1294d4..47a91c01d 100644
--- a/modules/image/image.field.inc
+++ b/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 a/modules/image/image.module b/modules/image/image.module
index a1d7327f4..e2a906654 100644
--- a/modules/image/image.module
+++ b/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 a/modules/locale/locale.admin.inc b/modules/locale/locale.admin.inc
index b19fce111..79ffbb3d6 100644
--- a/modules/locale/locale.admin.inc
+++ b/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 a/modules/menu/menu.admin.inc b/modules/menu/menu.admin.inc
index c73af82a4..3483ee6d2 100644
--- a/modules/menu/menu.admin.inc
+++ b/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 a/modules/node/content_types.inc b/modules/node/content_types.inc
index 70112c473..8bca4653b 100644
--- a/modules/node/content_types.inc
+++ b/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 a/modules/node/node.admin.inc b/modules/node/node.admin.inc
index 4dd932307..11a818a97 100644
--- a/modules/node/node.admin.inc
+++ b/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 a/modules/node/node.module b/modules/node/node.module
index c5b069d99..d9c137996 100644
--- a/modules/node/node.module
+++ b/modules/node/node.module
@@ -1695,7 +1695,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
  */
@@ -2129,10 +2133,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) {
@@ -2168,10 +2174,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 a/modules/node/node.pages.inc b/modules/node/node.pages.inc
index a6d5c0a0b..d18e7a779 100644
--- a/modules/node/node.pages.inc
+++ b/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 a/modules/poll/poll.module b/modules/poll/poll.module
index 7d012e6fd..bcd8e9e8d 100644
--- a/modules/poll/poll.module
+++ b/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 a/modules/profile/profile.admin.inc b/modules/profile/profile.admin.inc
index d6e535598..1a2f792fc 100644
--- a/modules/profile/profile.admin.inc
+++ b/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 a/modules/rdf/rdf.module b/modules/rdf/rdf.module
index 0c6ea4f8a..b7d5b4884 100644
--- a/modules/rdf/rdf.module
+++ b/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 a/modules/search/search.pages.inc b/modules/search/search.pages.inc
index 02d283e70..6bbb88942 100644
--- a/modules/search/search.pages.inc
+++ b/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 a/modules/shortcut/shortcut.admin.inc b/modules/shortcut/shortcut.admin.inc
index bb9f17da3..2db30f220 100644
--- a/modules/shortcut/shortcut.admin.inc
+++ b/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 a/modules/simpletest/simpletest.pages.inc b/modules/simpletest/simpletest.pages.inc
index 72d01e4a9..980075e84 100644
--- a/modules/simpletest/simpletest.pages.inc
+++ b/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 a/modules/syslog/syslog.module b/modules/syslog/syslog.module
index 1ee2ef6d8..5d95493c5 100644
--- a/modules/syslog/syslog.module
+++ b/modules/syslog/syslog.module
@@ -95,7 +95,23 @@ 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.
+ *
+ * @return
+ *   A string containing a pipe-delimited "|" log message.
  *
  * @ingroup themeable
  */
diff --git a/modules/system/system.admin.inc b/modules/system/system.admin.inc
index 3ca45af48..aff0429b3 100644
--- a/modules/system/system.admin.inc
+++ b/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 a/modules/system/system.module b/modules/system/system.module
index 822c559ec..d068c40fd 100644
--- a/modules/system/system.module
+++ b/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 a/modules/taxonomy/taxonomy.admin.inc b/modules/taxonomy/taxonomy.admin.inc
index 5ad7538ae..b8b6b3b5f 100644
--- a/modules/taxonomy/taxonomy.admin.inc
+++ b/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 a/modules/trigger/trigger.admin.inc b/modules/trigger/trigger.admin.inc
index 8e462fe98..c83a95979 100644
--- a/modules/trigger/trigger.admin.inc
+++ b/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 a/modules/update/update.manager.inc b/modules/update/update.manager.inc
index f72ce44c1..595c64222 100644
--- a/modules/update/update.manager.inc
+++ b/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 a/modules/update/update.module b/modules/update/update.module
index af81f6b01..faa79c567 100644
--- a/modules/update/update.module
+++ b/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 a/modules/update/update.report.inc b/modules/update/update.report.inc
index b33cea897..6a9d60d1b 100644
--- a/modules/update/update.report.inc
+++ b/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 a/modules/user/user.admin.inc b/modules/user/user.admin.inc
index 8c8f4387c..ee100630c 100644
--- a/modules/user/user.admin.inc
+++ b/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 a/modules/user/user.module b/modules/user/user.module
index 463dfa5bc..26d9edfdd 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -1338,7 +1338,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
  */