diff --git a/includes/form.inc b/includes/form.inc
index 93d0304b6a961a38b8046c96c18c5f82083a7da8..fcadc3c367cad5c2c7de686d370ea8e1087e9676 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 048980d033f2a3fffbf06ab33dafbb8a1eb32843..4b5ca3aedd8844193acbfc90ad9523dc5402c16d 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 7430cfe8c82458e144e3e78470fecaccdaed9adc..a33087c644407dc66fe250219707d47eb6099137 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 2e5c691bdb8bcbbe393505738275d919931d743c..6bfb95c4063f75dc31ff92893416cda56cc7670f 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 c19dd05db219142258b0f6ba7d47fc84571a2886..1a60911b14ba168c9ca7d44eb320852fd38efba4 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 = '';
diff --git a/modules/aggregator/aggregator.module b/modules/aggregator/aggregator.module
index d7343050e838ec265f2c5d952355047035846b44..b6cf40c3bba5446a348f89d3214ccea40e03462b 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 f8eb047afc29f084c477ac666a2f64a689f427ec..1613a501a9fcf89287dc96798d55e170402de78e 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 d185b0836caf5c7170cbada6f1e302480ff8e150..7a319430a0b04eee2ff9af6f01cb40290e470025 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 9d59383318c86ece81b971554d2840f7cf046e05..31401958f8edec8f3214bca6243b7b2b67c1118d 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 04d8e9bb48ce96880daa9589c6070226112d559c..65cd33608d7f51f9c08b1922b78f2ab1c327f600 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 21c16949cd3186c169ebb19526a9a77de750d146..f9305e808c30055f5ffd1e46cbc13142a7b714ac 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 c90f65d7565deb6e23f93aded88efdd64fb7eeb9..1ef9ef195626385b1acd7e5f96816c4116fde582 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 4f344f57716c5a8685453aec8510274ff938f07e..1f5ba88331c5a03ef8cb5f4375ec3b14be78b2ab 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 b5be9224cefc4a5be89d85eb1bb6c5aaad3e4408..5fd367a070964b31386b6bccf346e71741d8eb6c 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 c3765cfaa3d4e80b9aa4575651c2ad64e369bfd7..d470c9fd71d79228a5c5e5038b3a380d198ef72f 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 72a713afd734077df6ce30628cd3c645329c0fff..24ab04758d171331822a4b5bda1b90a7627eec26 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 57c47ae1e6fef3e7161b326e779656c759872cf2..ddd449e7e8dd3fb12e44ed661c51087572f63bf1 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 b3153e6477aaac794a18eae00b20b16a2624d73b..b925d7c2eb7d747bba5bb83b1a7d5688958070cc 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 25791934437fcf474fa0dee99d33bec9ee4ac8ae..5e6254c72581755231427e2547bfb176296231d2 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 a69d26031f4a394b8d28e19a45b620e65a6f2c0a..29be1489412e2e3cf2545297f8d12fc9e3e51233 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 ce3d842d30f9163c2299548d65a8c88a38ad55b4..e018e819d7f9938cfc8169c3decdbf6a35cf900c 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 49cb555ec429d5108d5cb85f7d626b68795b7f80..607089f6639f950ad11d2512cf238cb2a96d8b69 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 3ca88d5cf8069a011fa64b17b339105641f07181..8ef98a84a17a9641537b9c3ae936e636f0f42058 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 20c1294d4efcc850278f2c6efca3ded9c724be39..47a91c01d036fd2052433fa837483987621b8db9 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 a1d7327f497fe2147f443ca961483fa59a830ba9..e2a9066542753cbc3774263bcb3d56558d57ac4e 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 b19fce111631b6e8e9cd5b2a1dcb3bff7d7a3524..79ffbb3d60c4b08bd876d35e156ecf04d721fad6 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 c73af82a4c1095c6e22bfc82516c6b93426c9cba..3483ee6d2fce62e3a333f21888deddad84ab7144 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 70112c473de723b18739975ed5b0a2ac06c77555..8bca4653bc8c30bf0f6a9ebc8f32b6e7309b5739 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 4dd932307df8713c6491f8229b8a398fe615fc54..11a818a977d3011a8c57c2a68bbc71ade92e3714 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 c5b069d997ca379ae1bc63d3d227cc39f936da9e..d9c137996a456d071de3526e6213703820d1e9ae 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 a6d5c0a0b738194ebdba476e1c2546cedddf7977..d18e7a7796b89cb66293bae27dcccc2f823bc9b5 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 7d012e6fd48f2110afffc053903a2db35fa88ac8..bcd8e9e8d41ac4cebbb246c5ff9923e8067c9581 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 d6e535598ac3ab978d39b796a9abe34d596162f9..1a2f792fc2689532f575d144c0b2138774db53b1 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 0c6ea4f8a2dea6f07363e46995523be36f4c2a52..b7d5b488405575c6e4d5d4a06675dc71bd116971 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 02d283e70b5fa2eb93d3812dc947af1cbff99233..6bbb8894296df4cd38fd5731ed0cab8b7ee630c9 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 bb9f17da36186310ede87b801c8d1815e301df1d..2db30f22089670dafaaf8bd48057a682e191cef7 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 72d01e4a9d6017b33c030bffa02dd1d4c331c2ba..980075e8419a70f37dbdc7975a35f0cc16b4e5ec 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 1ee2ef6d8db94cf7ba079509c84aeebf2bb89ef6..5d95493c5ccc26f98843a925d09789b429cea49b 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 3ca45af485833d75c0932b75e61041aa8225f7f1..aff0429b36ce2786b4819f4402f460ce13c2cf52 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 @@ function theme_admin_block($variables) {
}
/**
- * 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 822c559ec667a7e45293bbe8ed40ce223fa71701..d068c40fd59cc362ec447a1cbac3e3c716cfbb56 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 5ad7538aeb79fed43d9dafc33642bc05081fe2ff..b8b6b3b5faa3006df717341515667e28eabb1f03 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 8e462fe98b9ecbc39c726f29d69912a94e81e2a3..c83a959799cf9836781a11a6d852ec26d03328e7 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 f72ce44c113c7fe877cd5597e8680bd7007460f5..595c64222224ecdf604d6a483d53ac06a52e803a 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 af81f6b01537ddca0a3bc9d3e92502c499d69861..faa79c567c079f9e4b2c5f6f299a68b4f86ffe54 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 b33cea89746af4a547cd54c8e11f08499f3ac83b..6a9d60d1b6661228aeece53e8d18583be3280fcd 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 8c8f4387c50301b5cbfcc7074ff787d28a03a0c1..ee100630c7188c99c5fadb7fbd49ccca2105e391 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 463dfa5bcc311f902497d4cb0979d77c60ed087a..26d9edfdd8b4ecd334a57e73a23e9f82cb778cc8 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
*/