Commit 3c3cee28 authored by Dries's avatar Dries

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

parent f8e14898
This diff is collapsed.
...@@ -1372,24 +1372,20 @@ function _menu_tree_data(&$links, $parents, $depth) { ...@@ -1372,24 +1372,20 @@ function _menu_tree_data(&$links, $parents, $depth) {
} }
/** /**
* Preprocess the rendered tree for theme_menu_tree. * Preprocesses the rendered tree for theme_menu_tree().
*
* @ingroup themeable
*/ */
function template_preprocess_menu_tree(&$variables) { function template_preprocess_menu_tree(&$variables) {
$variables['tree'] = $variables['tree']['#children']; $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 * @param $variables
* An associative array containing: * An associative array containing:
* - tree: @todo: document * - tree: An HTML string containing the tree's items.
*
* @return
* A themed HTML string.
* *
* @see template_preprocess_menu_tree()
* @ingroup themeable * @ingroup themeable
*/ */
function theme_menu_tree($variables) { function theme_menu_tree($variables) {
...@@ -1397,15 +1393,12 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
* - element: Structured array data for a menu link. * - element: Structured array data for a menu link.
* *
* @return
* A themed HTML string.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_menu_link(array $variables) { function theme_menu_link(array $variables) {
...@@ -1420,13 +1413,14 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
* - #link: A menu link array with 'title', 'href', and 'localized_options' * - element: A render element containing:
* keys. * - #link: A menu link array with 'title', 'href', and 'localized_options'
* - #active: A boolean indicating whether the local task is active. * keys.
* - #active: A boolean indicating whether the local task is active.
* *
* @ingroup themeable * @ingroup themeable
*/ */
...@@ -1451,12 +1445,13 @@ function theme_menu_local_task($variables) { ...@@ -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 * @param $variables
* An associative array containing: * An associative array containing:
* - #link: A menu link array with 'title', 'href', and 'localized_options' * - element: A render element containing:
* keys. * - #link: A menu link array with 'title', 'href', and 'localized_options'
* keys.
* *
* @ingroup themeable * @ingroup themeable
*/ */
......
...@@ -186,11 +186,11 @@ function pager_get_query_parameters() { ...@@ -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 * Menu callbacks that display paged query results should call theme('pager') to
* retrieve a pager control so that users can view other results. * retrieve a pager control so that users can view other results. Format a list
* Format a list of nearby pages with additional query results. * of nearby pages with additional query results.
* *
* @param $variables * @param $variables
* An associative array containing: * An associative array containing:
...@@ -201,9 +201,6 @@ function pager_get_query_parameters() { ...@@ -201,9 +201,6 @@ function pager_get_query_parameters() {
* the pager links. * the pager links.
* - quantity: The number of pages in the list. * - quantity: The number of pages in the list.
* *
* @return
* An HTML string that generates the query pager.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_pager($variables) { function theme_pager($variables) {
...@@ -321,7 +318,7 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
...@@ -331,9 +328,6 @@ function theme_pager($variables) { ...@@ -331,9 +328,6 @@ function theme_pager($variables) {
* - parameters: An associative array of query string parameters to append to * - parameters: An associative array of query string parameters to append to
* the pager links. * the pager links.
* *
* @return
* An HTML string that generates this piece of the query pager.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_pager_first($variables) { function theme_pager_first($variables) {
...@@ -352,7 +346,7 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
...@@ -363,9 +357,6 @@ function theme_pager_first($variables) { ...@@ -363,9 +357,6 @@ function theme_pager_first($variables) {
* - parameters: An associative array of query string parameters to append to * - parameters: An associative array of query string parameters to append to
* the pager links. * the pager links.
* *
* @return
* An HTML string that generates this piece of the query pager.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_pager_previous($variables) { function theme_pager_previous($variables) {
...@@ -394,7 +385,7 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
...@@ -405,9 +396,6 @@ function theme_pager_previous($variables) { ...@@ -405,9 +396,6 @@ function theme_pager_previous($variables) {
* - parameters: An associative array of query string parameters to append to * - parameters: An associative array of query string parameters to append to
* the pager links. * the pager links.
* *
* @return
* An HTML string that generates this piece of the query pager.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_pager_next($variables) { function theme_pager_next($variables) {
...@@ -435,7 +423,7 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
...@@ -445,9 +433,6 @@ function theme_pager_next($variables) { ...@@ -445,9 +433,6 @@ function theme_pager_next($variables) {
* - parameters: An associative array of query string parameters to append to * - parameters: An associative array of query string parameters to append to
* the pager links. * the pager links.
* *
* @return
* An HTML string that generates this piece of the query pager.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_pager_last($variables) { function theme_pager_last($variables) {
...@@ -467,7 +452,7 @@ 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 * @param $variables
* An associative array containing: * An associative array containing:
...@@ -479,9 +464,6 @@ function theme_pager_last($variables) { ...@@ -479,9 +464,6 @@ function theme_pager_last($variables) {
* - attributes: An associative array of HTML attributes to apply to a pager * - attributes: An associative array of HTML attributes to apply to a pager
* anchor tag. * anchor tag.
* *
* @return
* An HTML string that generates the link.
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_pager_link($variables) { function theme_pager_link($variables) {
......
This diff is collapsed.
...@@ -87,7 +87,12 @@ function _theme_load_offline_registry($theme, $base_theme = NULL, $theme_engine ...@@ -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 * @ingroup themeable
*/ */
...@@ -120,7 +125,7 @@ function theme_task_list($variables) { ...@@ -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. * Note: this function is not themeable.
* *
...@@ -180,7 +185,7 @@ function theme_install_page($variables) { ...@@ -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. * Note: this function is not themeable.
* *
...@@ -226,10 +231,13 @@ function theme_update_page($variables) { ...@@ -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. * - messages: An array of result messages.
*
* @ingroup themeable
*/ */
function theme_authorize_report($variables) { function theme_authorize_report($variables) {
$messages = $variables['messages']; $messages = $variables['messages'];
...@@ -251,11 +259,14 @@ function theme_authorize_report($variables) { ...@@ -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 * @param $variables
* An associative array containing:
* - message: The log message. * - message: The log message.
* - success: A boolean indicating failure or success. * - success: A boolean indicating failure or success.
*
* @ingroup themeable
*/ */
function theme_authorize_message($variables) { function theme_authorize_message($variables) {
$output = ''; $output = '';
......
...@@ -703,15 +703,13 @@ function aggregator_category_load($cid) { ...@@ -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 * @param $variables
* An associative array containing: * An associative array containing:
* - item: The item to be displayed. * - item: The item to be displayed.
* - feed: Not used. * - feed: Not used.
* *
* @return
* The item HTML.
* @ingroup themeable * @ingroup themeable
*/ */
function theme_aggregator_block_item($variables) { function theme_aggregator_block_item($variables) {
......
...@@ -234,14 +234,12 @@ function aggregator_categorize_items_submit($form, &$form_state) { ...@@ -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 * @param $variables
* An associative array containing: * 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 * @ingroup themeable
*/ */
function theme_aggregator_categorize_items($variables) { function theme_aggregator_categorize_items($variables) {
...@@ -371,13 +369,15 @@ function aggregator_page_rss() { ...@@ -371,13 +369,15 @@ function aggregator_page_rss() {
} }
/** /**
* Theme the RSS output. * Prints the RSS page for a feed.
* *
* @param $variables * @param $variables
* An associative array containing: * An associative array containing:
* - feeds: An array of the feeds to theme. * - feeds: An array of the feeds to theme.
* - category: A common category, if any, for all the feeds. * - category: A common category, if any, for all the feeds.
* *
* @return void
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_aggregator_page_rss($variables) { function theme_aggregator_page_rss($variables) {
...@@ -437,12 +437,14 @@ function aggregator_page_opml($cid = NULL) { ...@@ -437,12 +437,14 @@ function aggregator_page_opml($cid = NULL) {
} }
/** /**
* Theme the OPML feed output. * Prints the OPML page for a feed.
* *
* @param $variables * @param $variables
* An associative array containing: * An associative array containing:
* - feeds: An array of the feeds to theme. * - feeds: An array of the feeds to theme.
* *
* @return void
*
* @ingroup themeable * @ingroup themeable
*/ */
function theme_aggregator_page_opml($variables) { function theme_aggregator_page_opml($variables) {
......
...@@ -212,10 +212,14 @@ function _book_admin_table_tree($tree, &$form) { ...@@ -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() * @see book_admin_table()
* @ingroup themeable
*/ */
function theme_book_admin_table($variables) { function theme_book_admin_table($variables) {
$form = $variables['form']; $form = $variables['form'];
......
...@@ -338,7 +338,11 @@ function book_block_save($delta = '', $edit = array()) { ...@@ -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 * @ingroup themeable
*/ */
......
...@@ -222,7 +222,11 @@ function color_scheme_form($complete_form, &$form_state, $theme) { ...@@ -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 * @ingroup themeable
*/ */
......
...@@ -568,10 +568,8 @@ function comment_new_page_count($num_comments, $new_replies, $node) { ...@@ -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 * @ingroup themeable
*/ */
function theme_comment_block() { function theme_comment_block() {
...@@ -2204,7 +2202,7 @@ function template_preprocess_comment(&$variables) { ...@@ -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 * @param $variables
* An associative array containing: * An associative array containing:
......
...@@ -366,13 +366,12 @@ function dashboard_update() { ...@@ -366,13 +366,12 @@ function dashboard_update() {
} }
/** /**
* Theme the entire dashboard. * Returns HTML for the entire dashboard.
* *
* @param $variables * @param $variables
* - element: An associative array containing the properties of the dashboard region * An associative array containing:
* element. Properties used: #dashboard_region, #children * - element: A render element containing the properties of the dashboard
* @return * region element, #dashboard_region and #children.
* A string representing the themed dashboard.
* *
* @ingroup themeable * @ingroup themeable
*/ */
...@@ -383,15 +382,11 @@ function theme_dashboard($variables) { ...@@ -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 * @param $variables
* An associative array containing: * An associative array containing:
* - elements: An associative array containing the properties of the element. * - element: A render element containing a #message.
* Properties used: #message
* @return
* A themed HTML string representing the non-customizable part of the
* dashboard page.
* *
* @ingroup themeable * @ingroup themeable
*/ */
...@@ -402,13 +397,12 @@ function theme_dashboard_admin($variables) { ...@@ -402,13 +397,12 @@ function theme_dashboard_admin($variables) {
} }
/** /**
* Theme a generic dashboard region. * Returns HTML for a generic dashboard region.
* *
* @param $variables * @param $variables
* - element: An associative array containing the properties of the dashboard region * An associative array containing:
* element. Properties used: #dashboard_region, #children * - element: A render element containing the properties of the dashboard
* @return * region element, #dashboard_region and #children.
* A string representing the themed dashboard region.
* *
* @ingroup themeable * @ingroup themeable
*/ */
...@@ -425,13 +419,11 @@ function theme_dashboard_region($variables) { ...@@ -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 * @param $variables