diff --git a/core/modules/book/book-all-books-block.tpl.php b/core/modules/book/book-all-books-block.tpl.php
index f627963774b1c9209cac08cd6745a51569afb4c8..8e5343b35b6ef5c99d51b58f164c698caaf976ce 100644
--- a/core/modules/book/book-all-books-block.tpl.php
+++ b/core/modules/book/book-all-books-block.tpl.php
@@ -3,12 +3,17 @@
/**
* @file
* Default theme implementation for rendering book outlines within a block.
- * This template is used only when the block is configured to "show block on
- * all pages" which presents Multiple independent books on all pages.
+ *
+ * This template is used only when the block is configured to "show block on all
+ * pages", which presents multiple independent books on all pages.
*
* Available variables:
* - $book_menus: Array of book outlines keyed to the parent book ID. Call
* render() on each to print it as an unordered list.
+ *
+ * @see template_preprocess_book_all_books_block()
+ *
+ * @ingroup themeable
*/
?>
<?php foreach ($book_menus as $book_id => $menu): ?>
diff --git a/core/modules/book/book-export-html.tpl.php b/core/modules/book/book-export-html.tpl.php
index 4b25a766e18ce915b9e47cd1fabec4223f5e41fd..062a0bde1efbc3377a0413aa6b8b999117791692 100644
--- a/core/modules/book/book-export-html.tpl.php
+++ b/core/modules/book/book-export-html.tpl.php
@@ -14,6 +14,8 @@
* book-node-export-html.tpl.php.
*
* @see template_preprocess_book_export_html()
+ *
+ * @ingroup themeable
*/
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
diff --git a/core/modules/book/book-navigation.tpl.php b/core/modules/book/book-navigation.tpl.php
index 53f03c03d2d3f447d633ed11b9323b76f7c8400a..ed608f0f1b62b5d04cf935b0f5906cfcebea9630 100644
--- a/core/modules/book/book-navigation.tpl.php
+++ b/core/modules/book/book-navigation.tpl.php
@@ -1,14 +1,15 @@
<?php
/**
* @file
- * Default theme implementation to navigate books. Presented under nodes that
- * are a part of book outlines.
+ * Default theme implementation to navigate books.
+ *
+ * Presented under nodes that are a part of book outlines.
*
* Available variables:
- * - $tree: The immediate children of the current node rendered as an
- * unordered list.
- * - $current_depth: Depth of the current node within the book outline.
- * Provided for context.
+ * - $tree: The immediate children of the current node rendered as an unordered
+ * list.
+ * - $current_depth: Depth of the current node within the book outline. Provided
+ * for context.
* - $prev_url: URL to the previous node.
* - $prev_title: Title of the previous node.
* - $parent_url: URL to the parent node.
@@ -18,14 +19,16 @@
* - $next_title: Title of the next node.
* - $has_links: Flags TRUE whenever the previous, parent or next data has a
* value.
- * - $book_id: The book ID of the current outline being viewed. Same as the
- * node ID containing the entire outline. Provided for context.
- * - $book_url: The book/node URL of the current outline being viewed.
- * Provided as an option. Not used by default.
+ * - $book_id: The book ID of the current outline being viewed. Same as the node
+ * ID containing the entire outline. Provided for context.
+ * - $book_url: The book/node URL of the current outline being viewed. Provided
+ * as an option. Not used by default.
* - $book_title: The book/node title of the current outline being viewed.
* Provided as an option. Not used by default.
*
* @see template_preprocess_book_navigation()
+ *
+ * @ingroup themeable
*/
?>
<?php if ($tree || $has_links): ?>
diff --git a/core/modules/book/book-node-export-html.tpl.php b/core/modules/book/book-node-export-html.tpl.php
index ef6c3224cfb5581f4f046ef79ba55973619c893a..0c2c67cc213dd6eae1cff03f0e0586c78c4745fb 100644
--- a/core/modules/book/book-node-export-html.tpl.php
+++ b/core/modules/book/book-node-export-html.tpl.php
@@ -2,8 +2,7 @@
/**
* @file
- * Default theme implementation for rendering a single node in a printer
- * friendly outline.
+ * Default theme implementation for a single node in a printer-friendly outline.
*
* @see book-node-export-html.tpl.php
* Where it is collected and printed out.
@@ -15,6 +14,8 @@
* - $children: All the child nodes recursively rendered through this file.
*
* @see template_preprocess_book_node_export_html()
+ *
+ * @ingroup themeable
*/
?>
<div id="node-<?php print $node->nid; ?>" class="section-<?php print $depth; ?>">
diff --git a/core/modules/book/book.admin.inc b/core/modules/book/book.admin.inc
index 7b9dea390f5bdc9c66d018b889d41c6d5368bf10..e37c7fc6d05a454d4ad237b6f1d16731750b5435 100644
--- a/core/modules/book/book.admin.inc
+++ b/core/modules/book/book.admin.inc
@@ -6,7 +6,11 @@
*/
/**
- * Returns an administrative overview of all books.
+ * Page callback: Returns an administrative overview of all books.
+ *
+ * Path: admin/content/book
+ *
+ * @see book_menu()
*/
function book_admin_overview() {
$rows = array();
@@ -22,10 +26,12 @@ function book_admin_overview() {
}
/**
- * Builds and returns the book settings form.
+ * Form constructor for the book settings form.
*
- * @see book_admin_settings_validate()
+ * Path: admin/content/book/settings
*
+ * @see book_menu()
+ * @see book_admin_settings_validate()
* @ingroup forms
*/
function book_admin_settings() {
@@ -52,9 +58,7 @@ function book_admin_settings() {
}
/**
- * Validate the book settings form.
- *
- * @see book_admin_settings()
+ * Form validation handler for book_admin_settings().
*/
function book_admin_settings_validate($form, &$form_state) {
$child_type = $form_state['values']['book_child_type'];
@@ -64,11 +68,17 @@ function book_admin_settings_validate($form, &$form_state) {
}
/**
- * Build the form to administrate the hierarchy of a single book.
+ * Form constructor for administering a single book's hierarchy.
*
- * @see book_admin_edit_submit()
+ * Path: admin/content/book/%node
*
- * @ingroup forms.
+ * @param $node
+ * The node of the top-level page in the book.
+ *
+ * @see book_menu()
+ * @see book_admin_edit_validate()
+ * @see book_admin_edit_submit()
+ * @ingroup forms
*/
function book_admin_edit($form, $form_state, $node) {
drupal_set_title($node->title);
@@ -83,9 +93,11 @@ function book_admin_edit($form, $form_state, $node) {
}
/**
- * Check that the book has not been changed while using the form.
+ * Form validation handler for book_admin_edit().
*
- * @see book_admin_edit()
+ * Checks that the book has not been changed while using the form.
+ *
+ * @see book_admin_edit_submit()
*/
function book_admin_edit_validate($form, &$form_state) {
if ($form_state['values']['tree_hash'] != $form_state['values']['tree_current_hash']) {
@@ -94,12 +106,12 @@ function book_admin_edit_validate($form, &$form_state) {
}
/**
- * Handle submission of the book administrative page form.
+ * Form submission handler for book_admin_edit().
*
* This function takes care to save parent menu items before their children.
* Saving menu items in the incorrect order can break the menu tree.
*
- * @see book_admin_edit()
+ * @see book_admin_edit_validate()
* @see menu_overview_form_submit()
*/
function book_admin_edit_submit($form, &$form_state) {
@@ -139,7 +151,12 @@ function book_admin_edit_submit($form, &$form_state) {
}
/**
- * Build the table portion of the form for the book administration page.
+ * Builds the table portion of the form for the book administration page.
+ *
+ * @param $node
+ * The node of the top-level page in the book.
+ * @param $form
+ * The form that is being modified.
*
* @see book_admin_edit()
*/
@@ -169,7 +186,15 @@ function _book_admin_table($node, &$form) {
}
/**
- * Recursive helper to build the main table in the book administration page form.
+ * Helps build the main table in the book administration page form.
+ *
+ * @param $tree
+ * A subtree of the book menu hierarchy.
+ * @param $form
+ * The form that is being modified.
+ *
+ * @return
+ * The form that is being modified.
*
* @see book_admin_edit()
*/
diff --git a/core/modules/book/book.install b/core/modules/book/book.install
index e92aca6e43ceb5ac7c56b3dae34c1b1a8ab1db59..899ee8147bd5e9507fe0096db6bf2a992c2bd948 100644
--- a/core/modules/book/book.install
+++ b/core/modules/book/book.install
@@ -28,6 +28,9 @@ function book_uninstall() {
menu_cache_clear_all();
}
+/**
+ * Creates the book content type.
+ */
function _book_install_type_create() {
// Create an additional node type.
$book_node_type = array(
diff --git a/core/modules/book/book.module b/core/modules/book/book.module
index 10809843a85056d31707ea74069cbc744926aaa9..0a6637cef02a67f60a859a265a667ba10c30e83f 100644
--- a/core/modules/book/book.module
+++ b/core/modules/book/book.module
@@ -84,7 +84,12 @@ function book_permission() {
}
/**
- * Inject links into $node as needed.
+ * Adds relevant book links to the node's links.
+ *
+ * @param $node
+ * The book page node to add links to.
+ * @param $view_mode
+ * The view mode of the node.
*/
function book_node_view_link($node, $view_mode) {
$links = array();
@@ -190,14 +195,30 @@ function book_menu() {
}
/**
- * Menu item access callback - determine if the outline tab is accessible.
+ * Access callback: Determines if the outline tab is accessible.
+ *
+ * Path:
+ * - admin/content/book/%node
+ * - node/%node/outline
+ *
+ * @param $node
+ * The node whose outline tab is to be viewed.
+ *
+ * @see book_menu()
*/
function _book_outline_access($node) {
return user_access('administer book outlines') && node_access('view', $node);
}
/**
- * Menu item access callback - determine if the user can remove nodes from the outline.
+ * Access callback: Determines if the user can remove nodes from the outline.
+ *
+ * Path: node/%node/outline/remove
+ *
+ * @param $node
+ * The node to remove from the outline.
+ *
+ * @see book_menu()
*/
function _book_outline_remove_access($node) {
return isset($node->book) && ($node->book['bid'] != $node->nid) && _book_outline_access($node);
@@ -348,6 +369,9 @@ function theme_book_title_link($variables) {
*
* This list may be used for generating a list of all the books, or for building
* the options for a form select.
+ *
+ * @return
+ * An array of all books.
*/
function book_get_books() {
$all_books = &drupal_static(__FUNCTION__);
@@ -416,7 +440,7 @@ function book_form_node_form_alter(&$form, &$form_state, $form_id) {
}
/**
- * Submit handler to change a node's book.
+ * Form submission handler for node_form().
*
* This handler is run when JavaScript is disabled. It triggers the form to
* rebuild so that the "Parent item" options are changed to reflect the newly
@@ -425,6 +449,7 @@ function book_form_node_form_alter(&$form, &$form_state, $form_id) {
* book_form_update() Ajax callback instead.
*
* @see book_form_update()
+ * @see book_form_node_form_alter()
*/
function book_pick_book_nojs_submit($form, &$form_state) {
$form_state['node']->book = $form_state['values']['book'];
@@ -432,11 +457,17 @@ function book_pick_book_nojs_submit($form, &$form_state) {
}
/**
- * Build the parent selection form element for the node form or outline tab.
+ * Builds the parent selection form element for the node form or outline tab.
*
* This function is also called when generating a new set of options during the
- * Ajax callback, so an array is returned that can be used to replace an existing
- * form element.
+ * Ajax callback, so an array is returned that can be used to replace an
+ * existing form element.
+ *
+ * @param $book_link
+ * A fully loaded menu link that is part of the book hierarchy.
+ *
+ * @return
+ * A parent selection form element.
*/
function _book_parent_select($book_link) {
if (variable_get('menu_override_parent_selector', FALSE)) {
@@ -479,7 +510,10 @@ function _book_parent_select($book_link) {
}
/**
- * Build the common elements of the book form for the node and outline forms.
+ * Builds the common elements of the book form for the node and outline forms.
+ *
+ * @param $node
+ * The node whose form is being viewed.
*/
function _book_add_form_elements(&$form, &$form_state, $node) {
// If the form is being processed during the Ajax callback of our book bid
@@ -577,10 +611,17 @@ function book_form_update($form, $form_state) {
}
/**
- * Common helper function to handles additions and updates to the book outline.
+ * Handles additions and updates to the book outline.
+ *
+ * This common helper function performs all additions and updates to the book
+ * outline through node addition, node editing, node deletion, or the outline
+ * tab.
*
- * Performs all additions and updates to the book outline through node addition,
- * node editing, node deletion, or the outline tab.
+ * @param $node
+ * The node that is being saved, added, deleted, or moved.
+ *
+ * @return
+ * TRUE if the menu link was saved; FALSE otherwise.
*/
function _book_update_outline($node) {
if (empty($node->book['bid'])) {
@@ -643,7 +684,7 @@ function _book_update_outline($node) {
}
/**
- * Update the bid for a page and its children when it is moved to a new book.
+ * Updates the book ID of a page and its children when it moves to a new book.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
@@ -665,16 +706,17 @@ function book_update_bid($book_link) {
}
/**
- * Get the book menu tree for a page, and return it as a linear array.
+ * Gets the book menu tree for a page and returns it as a linear array.
*
* @param $book_link
* A fully loaded menu link that is part of the book hierarchy.
+ *
* @return
* A linear array of menu links in the order that the links are shown in the
* menu, so the previous and next pages are the elements before and after the
- * element corresponding to $node. The children of $node (if any) will come
- * immediately after it in the array, and links will only be fetched as deep
- * as one level deeper than $book_link.
+ * element corresponding to the current node. The children of the current node
+ * (if any) will come immediately after it in the array, and links will only
+ * be fetched as deep as one level deeper than $book_link.
*/
function book_get_flat_menu($book_link) {
$flat = &drupal_static(__FUNCTION__, array());
@@ -690,7 +732,14 @@ function book_get_flat_menu($book_link) {
}
/**
- * Recursive helper function for book_get_flat_menu().
+ * Recursively converts a tree of menu links to a flat array.
+ *
+ * @param $tree
+ * A tree of menu links in an array.
+ * @param $flat
+ * A flat array of the menu links from $tree.
+ *
+ * @see book_get_flat_menu().
*/
function _book_flatten_menu($tree, &$flat) {
foreach ($tree as $data) {
@@ -705,6 +754,13 @@ function _book_flatten_menu($tree, &$flat) {
/**
* Fetches the menu link for the previous page of the book.
+ *
+ * @param $book_link
+ * A fully loaded menu link that is part of the book hierarchy.
+ *
+ * @return
+ * A fully loaded menu link for the page before the one represented in
+ * $book_link.
*/
function book_prev($book_link) {
// If the parent is zero, we are at the start of a book.
@@ -740,6 +796,13 @@ function book_prev($book_link) {
/**
* Fetches the menu link for the next page of the book.
+ *
+ * @param $book_link
+ * A fully loaded menu link that is part of the book hierarchy.
+ *
+ * @return
+ * A fully loaded menu link for the page after the one represented in
+ * $book_link.
*/
function book_next($book_link) {
$flat = book_get_flat_menu($book_link);
@@ -755,7 +818,13 @@ function book_next($book_link) {
}
/**
- * Format the menu links for the child pages of the current page.
+ * Formats the menu links for the child pages of the current page.
+ *
+ * @param $book_link
+ * A fully loaded menu link that is part of the book hierarchy.
+ *
+ * @return
+ * HTML for the links to the child pages of the current page.
*/
function book_children($book_link) {
$flat = book_get_flat_menu($book_link);
@@ -784,7 +853,13 @@ function book_children($book_link) {
}
/**
- * Generate the corresponding menu name from a book ID.
+ * Generates the corresponding menu name from a book ID.
+ *
+ * @param $bid
+ * The book ID for which to make a menu name.
+ *
+ * @return
+ * The menu name.
*/
function book_menu_name($bid) {
return 'book-toc-' . $bid;
@@ -824,7 +899,7 @@ function book_node_view($node, $view_mode) {
/**
* Implements hook_page_alter().
*
- * Add the book menu to the list of menus used to build the active trail when
+ * Adds the book menu to the list of menus used to build the active trail when
* viewing a book page.
*/
function book_page_alter(&$page) {
@@ -940,14 +1015,24 @@ function book_node_prepare($node) {
}
/**
- * Find the depth limit for items in the parent select.
+ * Finds the depth limit for items in the parent select.
+ *
+ * @param $book_link
+ * A fully loaded menu link that is part of the book hierarchy.
+ *
+ * @return
+ * The depth limit for items in the parent select.
*/
function _book_parent_depth_limit($book_link) {
return MENU_MAX_DEPTH - 1 - (($book_link['mlid'] && $book_link['has_children']) ? menu_link_children_relative_depth($book_link) : 0);
}
/**
- * Form altering function for the confirm form for a single node deletion.
+ * Implements hook_form_FORM_ID_alter().
+ *
+ * Alters the confirm form for a single node deletion.
+ *
+ * @see node_delete_confirm()
*/
function book_form_node_delete_confirm_alter(&$form, $form_state) {
$node = node_load($form['nid']['#value']);
@@ -961,23 +1046,29 @@ function book_form_node_delete_confirm_alter(&$form, $form_state) {
}
/**
- * Return an array with default values for a book link.
+ * Returns an array with default values for a book page's menu link.
+ *
+ * @param $nid
+ * The ID of the node whose menu link is being created.
+ *
+ * @return
+ * The default values for the menu link.
*/
function _book_link_defaults($nid) {
return array('original_bid' => 0, 'menu_name' => '', 'nid' => $nid, 'bid' => 0, 'router_path' => 'node/%', 'plid' => 0, 'mlid' => 0, 'has_children' => 0, 'weight' => 0, 'module' => 'book', 'options' => array());
}
/**
- * Process variables for book-all-books-block.tpl.php.
+ * Processes variables for book-all-books-block.tpl.php.
*
- * The $variables array contains the following arguments:
- * - $book_menus
+ * All non-renderable elements are removed so that the template has full access
+ * to the structured data but can also simply iterate over all elements and
+ * render them (as in the default template).
*
- * All non-renderable elements are removed so that the template has full
- * access to the structured data but can also simply iterate over all
- * elements and render them (as in the default template).
+ * The $variables array contains the following elements:
+ * - book_menus
*
- * @see book-navigation.tpl.php
+ * @see book-all-books-block.tpl.php
*/
function template_preprocess_book_all_books_block(&$variables) {
// Remove all non-renderable elements.
@@ -989,10 +1080,10 @@ function template_preprocess_book_all_books_block(&$variables) {
}
/**
- * Process variables for book-navigation.tpl.php.
+ * Processes variables for book-navigation.tpl.php.
*
- * The $variables array contains the following arguments:
- * - $book_link
+ * The $variables array contains the following elements:
+ * - book_link
*
* @see book-navigation.tpl.php
*/
@@ -1049,13 +1140,13 @@ function template_preprocess_book_navigation(&$variables) {
/**
* Recursively processes and formats menu items for book_toc().
*
- * This helper function recursively modifies the $toc array for each item in
- * $tree, ignoring items in the exclude array or at a depth greater than the
- * limit. Truncates titles over thirty characters and appends an indentation
- * string incremented by depth.
+ * This helper function recursively modifies the table of contents array for
+ * each item in the menu tree, ignoring items in the exclude array or at a depth
+ * greater than the limit. Truncates titles over thirty characters and appends
+ * an indentation string incremented by depth.
*
* @param $tree
- * The data structure of the book's menu tree. Includes hidden links.
+ * The data structure of the book's menu tree. Includes hidden links.
* @param $indent
* A string appended to each menu item title. Increments by '--' per depth
* level.
@@ -1063,8 +1154,8 @@ function template_preprocess_book_navigation(&$variables) {
* Reference to the table of contents array. This is modified in place, so the
* function does not have a return value.
* @param $exclude
- * Optional array of mlid values. Any link whose mlid is in this array will be
- * excluded (along with its children).
+ * Optional array of menu link ID values. Any link whose menu link ID is in
+ * this array will be excluded (along with its children).
* @param $depth_limit
* Any link deeper than this value will be excluded (along with its children).
*/
@@ -1092,10 +1183,12 @@ function _book_toc_recurse($tree, $indent, &$toc, $exclude, $depth_limit) {
* @param $depth_limit
* Any link deeper than this value will be excluded (along with its children).
* @param $exclude
- * Optional array of mlid values. Any link whose mlid is in this array
- * will be excluded (along with its children).
+ * Optional array of menu link ID values. Any link whose menu link ID is in
+ * this array will be excluded (along with its children).
+ *
* @return
- * An array of mlid, title pairs for use as options for selecting a book page.
+ * An array of (menu link ID, title) pairs for use as options for selecting a
+ * book page.
*/
function book_toc($bid, $depth_limit, $exclude = array()) {
$tree = menu_tree_all_data(book_menu_name($bid));
@@ -1106,12 +1199,12 @@ function book_toc($bid, $depth_limit, $exclude = array()) {
}
/**
- * Process variables for book-export-html.tpl.php.
+ * Processes variables for book-export-html.tpl.php.
*
- * The $variables array contains the following arguments:
- * - $title
- * - $contents
- * - $depth
+ * The $variables array contains the following elements:
+ * - title
+ * - contents
+ * - depth
*
* @see book-export-html.tpl.php
*/
@@ -1126,16 +1219,16 @@ function template_preprocess_book_export_html(&$variables) {
}
/**
- * Traverse the book tree to build printable or exportable output.
+ * Traverses the book tree to build printable or exportable output.
*
- * During the traversal, the $visit_func() callback is applied to each
- * node, and is called recursively for each child of the node (in weight,
- * title order).
+ * During the traversal, the $visit_func() callback is applied to each node and
+ * is called recursively for each child of the node (in weight, title order).
*
* @param $tree
* A subtree of the book menu hierarchy, rooted at the current page.
* @param $visit_func
* A function callback to be called upon visiting a node in the tree.
+ *
* @return
* The output generated in visiting each node.
*/
@@ -1167,14 +1260,15 @@ function book_export_traverse($tree, $visit_func) {
/**
* Generates printer-friendly HTML for a node.
*
- * @see book_export_traverse()
- *
* @param $node
* The node that will be output.
* @param $children
* All the rendered child nodes within the current node.
+ *
* @return
* The HTML generated for the given node.
+ *
+ * @see book_export_traverse()
*/
function book_node_export($node, $children = '') {
$build = node_view($node, 'print');
@@ -1186,11 +1280,11 @@ function book_node_export($node, $children = '') {
}
/**
- * Process variables for book-node-export-html.tpl.php.
+ * Processes variables for book-node-export-html.tpl.php.
*
- * The $variables array contains the following arguments:
- * - $node
- * - $children
+ * The $variables array contains the following elements:
+ * - node
+ * - children
*
* @see book-node-export-html.tpl.php
*/
@@ -1201,7 +1295,7 @@ function template_preprocess_book_node_export_html(&$variables) {
}
/**
- * Determine if a given node type is in the list of types allowed for books.
+ * Determines if a given node type is in the list of types allowed for books.
*/
function book_type_is_allowed($type) {
return in_array($type, variable_get('book_allowed_types', array('book')));
@@ -1210,8 +1304,8 @@ function book_type_is_allowed($type) {
/**
* Implements hook_node_type_update().
*
- * Update book module's persistent variables if the machine-readable name of a
- * node type is changed.
+ * Updates the Book module's persistent variables if the machine-readable name
+ * of a node type is changed.
*/
function book_node_type_update($type) {
if (!empty($type->old_type) && $type->old_type != $type->type) {
@@ -1233,9 +1327,18 @@ function book_node_type_update($type) {
}
/**
+ * Gets a book menu link by its menu link ID.
+ *
* Like menu_link_load(), but adds additional data from the {book} table.
*
* Do not call when loading a node, since this function may call node_load().
+ *
+ * @param $mlid
+ * The menu link ID of the menu item.
+ *
+ * @return
+ * A menu link, with the link translated for rendering and data added from the
+ * {book} table.
*/
function book_link_load($mlid) {
if ($item = db_query("SELECT * FROM {menu_links} ml INNER JOIN {book} b ON b.mlid = ml.mlid LEFT JOIN {menu_router} m ON m.path = ml.router_path WHERE ml.mlid = :mlid", array(
@@ -1249,13 +1352,15 @@ function book_link_load($mlid) {
}
/**
- * Get the data representing a subtree of the book hierarchy.
+ * Gets the data representing a subtree of the book hierarchy.
*
* The root of the subtree will be the link passed as a parameter, so the
- * returned tree will contain this item and all its descendents in the menu tree.
+ * returned tree will contain this item and all its descendents in the menu
+ * tree.
*
* @param $link
* A fully loaded menu link.
+ *
* @return
* An subtree of menu links in an array, in the order they should be rendered.
*/
diff --git a/core/modules/book/book.pages.inc b/core/modules/book/book.pages.inc
index 1617f008503977e66e66e6122444864b9ae4bd9a..e5f0832f3b93441b5490ddacb44f317c20f70673 100644
--- a/core/modules/book/book.pages.inc
+++ b/core/modules/book/book.pages.inc
@@ -6,7 +6,11 @@
*/
/**
- * Menu callback; prints a listing of all books.
+ * Page callback: Prints a listing of all books.
+ *
+ * Path: book
+ *
+ * @see book_menu()
*/
function book_render() {
$book_list = array();
@@ -18,25 +22,28 @@ function book_render() {
}
/**
- * Menu callback; Generates various representation of a book page and its children.
- *
- * The function delegates the generation of output to helper functions.
- * The function name is derived by prepending 'book_export_' to the
- * given output type. So, e.g., a type of 'html' results in a call to
- * the function book_export_html().
+ * Page callback: Generates representations of a book page and its children.
*
- * @param $type
- * A string encoding the type of output requested. The following
- * types are currently supported in book module:
+ * Path: book/export/%/%
*
- * - html: HTML (printer friendly output)
+ * The function delegates the generation of output to helper functions. The
+ * function name is derived by prepending 'book_export_' to the given output
+ * type. So, e.g., a type of 'html' results in a call to the function
+ * book_export_html().
*
+ * @param $type
+ * A string encoding the type of output requested. The following types are
+ * currently supported in book module:
+ * - html: Printer-friendly HTML.
* Other types may be supported in contributed modules.
* @param $nid
* An integer representing the node id (nid) of the node to export
+ *
* @return
- * A string representing the node and its children in the book hierarchy
- * in a format determined by the $type parameter.
+ * A string representing the node and its children in the book hierarchy in a
+ * format determined by the $type parameter.
+ *
+ * @see book_menu()
*/
function book_export($type, $nid) {
$type = drupal_strtolower($type);
@@ -55,16 +62,16 @@ function book_export($type, $nid) {
/**
* This function is called by book_export() to generate HTML for export.
*
- * The given node is /embedded to its absolute depth in a top level
- * section/. For example, a child node with depth 2 in the hierarchy
- * is contained in (otherwise empty) <div> elements
- * corresponding to depth 0 and depth 1. This is intended to support
- * WYSIWYG output - e.g., level 3 sections always look like level 3
- * sections, no matter their depth relative to the node selected to be
- * exported as printer-friendly HTML.
+ * The given node is embedded to its absolute depth in a top level section. For
+ * example, a child node with depth 2 in the hierarchy is contained in
+ * (otherwise empty) <div> elements corresponding to depth 0 and depth 1.
+ * This is intended to support WYSIWYG output - e.g., level 3 sections always
+ * look like level 3 sections, no matter their depth relative to the node
+ * selected to be exported as printer-friendly HTML.
*
* @param $nid
* An integer representing the node id (nid) of the node to export.
+ *
* @return
* A string containing HTML representing the node and its children in
* the book hierarchy.
@@ -88,7 +95,14 @@ function book_export_html($nid) {
}
/**
- * Menu callback; show the outline form for a single node.
+ * Page callback: Shows the outline form for a single node.
+ *
+ * Path: node/%node/outline
+ *
+ * @param $node
+ * The book node for which to show the outline.
+ *
+ * @see book_menu()
*/
function book_outline($node) {
drupal_set_title($node->title);
@@ -96,11 +110,15 @@ function book_outline($node) {
}
/**
- * Build the form to handle all book outline operations via the outline tab.
+ * Form constructor for the book outline form.
+ *
+ * Allows handling of all book outline operations via the outline tab.
+ *
+ * @param $node
+ * The book node for which to show the outline.
*
* @see book_outline_form_submit()
* @see book_remove_button_submit()
- *
* @ingroup forms
*/
function book_outline_form($form, &$form_state, $node) {
@@ -140,18 +158,20 @@ function book_outline_form($form, &$form_state, $node) {
}
/**
- * Button submit function to redirect to removal confirm form.
+ * Form submission handler for book_outline_form().
*
- * @see book_outline_form()
+ * Redirects to removal confirmation form.
+ *
+ * @see book_outline_form_submit()
*/
function book_remove_button_submit($form, &$form_state) {
$form_state['redirect'] = 'node/' . $form['#node']->nid . '/outline/remove';
}
/**
- * Handles book outline form submissions from the outline tab.
+ * Form submission handler for book_outline_form().
*
- * @see book_outline_form()
+ * @see book_remove_button_submit()
*/
function book_outline_form_submit($form, &$form_state) {
$node = $form['#node'];
@@ -181,10 +201,15 @@ function book_outline_form_submit($form, &$form_state) {
}
/**
- * Menu callback; builds a form to confirm removal of a node from the book.
+ * Form constructor to confirm removal of a node from a book.
*
- * @see book_remove_form_submit()
+ * Path: node/%node/outline/remove
+ *
+ * @param $node
+ * The node to delete.
*
+ * @see book_remove_form_submit()
+ * @see book_menu()
* @ingroup forms
*/
function book_remove_form($form, &$form_state, $node) {
@@ -202,9 +227,7 @@ function book_remove_form($form, &$form_state, $node) {
}
/**
- * Confirm form submit function to remove a node from the book.
- *
- * @see book_remove_form()
+ * Form submission handler for book_remove_form().
*/
function book_remove_form_submit($form, &$form_state) {
$node = $form['#node'];