From 6242e0ee0c1d3d8a276bfee810c47ef4e6e95812 Mon Sep 17 00:00:00 2001
From: Lars Toomre <ltoomre@23809.no-reply.drupal.org>
Date: Thu, 18 Oct 2012 07:14:52 -0400
Subject: [PATCH] Issue 1807688 by Lars Toomre: Further clean up of API docs
 for Book module.

---
 core/modules/book/book.admin.css                   |    2 +-
 core/modules/book/book.admin.inc                   |   15 +++--
 core/modules/book/book.install                     |    2 +-
 core/modules/book/book.js                          |    1 -
 core/modules/book/book.module                      |   61 ++++++++++++++-----
 core/modules/book/book.pages.inc                   |   11 ++++
 core/modules/book/book.theme-rtl.css               |    3 +-
 core/modules/book/book.theme.css                   |    3 +-
 .../book/lib/Drupal/book/Tests/BookTest.php        |   62 ++++++++++++++-----
 9 files changed, 114 insertions(+), 46 deletions(-)

diff --git a/core/modules/book/book.admin.css b/core/modules/book/book.admin.css
index 2f8f8dc..08e1cb1 100644
--- a/core/modules/book/book.admin.css
+++ b/core/modules/book/book.admin.css
@@ -1,6 +1,6 @@
 /**
  * @file
- * Admin styles for book module.
+ * Administration styles for Book module.
  */
 
 /**
diff --git a/core/modules/book/book.admin.inc b/core/modules/book/book.admin.inc
index fbd8dda..eb283e8 100644
--- a/core/modules/book/book.admin.inc
+++ b/core/modules/book/book.admin.inc
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Admin page callbacks for the book module.
+ * Administration page callbacks for the Book module.
  */
 
 use Drupal\node\Node;
@@ -10,6 +10,9 @@
 /**
  * Page callback: Returns an administrative overview of all books.
  *
+ * @return string
+ *   A HTML-formatted string with the administrative page content.
+ *
  * @see book_menu()
  */
 function book_admin_overview() {
@@ -73,6 +76,8 @@ function book_admin_settings($form, &$form_state) {
 
 /**
  * Form validation handler for book_admin_settings().
+ *
+ * @see book_admin_settings_submit()
  */
 function book_admin_settings_validate($form, &$form_state) {
   $child_type = $form_state['values']['book_child_type'];
@@ -180,7 +185,7 @@ function book_admin_edit_submit($form, &$form_state) {
  * @param Drupal\node\Node $node
  *   The node of the top-level page in the book.
  * @param $form
- *   The form that is being modified.
+ *   The form that is being modified, passed by reference
  *
  * @see book_admin_edit()
  */
@@ -215,10 +220,10 @@ function _book_admin_table(Node $node, &$form) {
  * @param $tree
  *   A subtree of the book menu hierarchy.
  * @param $form
- *   The form that is being modified.
+ *   The form that is being modified, passed by reference.
  *
  * @return
- *   The form that is being modified.
+ *   The modified form array.
  *
  * @see book_admin_edit()
  */
@@ -266,7 +271,7 @@ function _book_admin_table_tree($tree, &$form) {
 /**
  * Returns HTML for a book administration form.
  *
- * @param $variables
+ * @param array $variables
  *   An associative array containing:
  *   - form: A render element representing the form.
  *
diff --git a/core/modules/book/book.install b/core/modules/book/book.install
index 2293c46..e9abf1d 100644
--- a/core/modules/book/book.install
+++ b/core/modules/book/book.install
@@ -88,7 +88,7 @@ function book_schema() {
 }
 
 /**
- * Move book settings from variables to config.
+ * Move Book settings from variables to config.
  *
  * @ingroup config_upgrade
  */
diff --git a/core/modules/book/book.js b/core/modules/book/book.js
index 301c67f..47de1a2 100644
--- a/core/modules/book/book.js
+++ b/core/modules/book/book.js
@@ -3,7 +3,6 @@
  * Javascript behaviors for the Book module.
  */
 
-
 (function ($) {
 
 "use strict";
diff --git a/core/modules/book/book.module b/core/modules/book/book.module
index 7c43e28..a508dc7 100644
--- a/core/modules/book/book.module
+++ b/core/modules/book/book.module
@@ -207,6 +207,9 @@ function book_menu() {
  * @param Drupal\node\Node $node
  *   The node whose outline tab is to be viewed.
  *
+ * @return
+ *   A Boolean TRUE if the current user has the requested permission.
+ *
  * @see book_menu()
  */
 function _book_outline_access(Node $node) {
@@ -219,6 +222,9 @@ function _book_outline_access(Node $node) {
  * @param Drupal\node\Node $node
  *   The node to remove from the outline.
  *
+ * @return
+ *   A Boolean TRUE if the current user has the requested permission.
+ *
  * @see book_menu()
  */
 function _book_outline_remove_access(Node $node) {
@@ -230,6 +236,12 @@ function _book_outline_remove_access(Node $node) {
  *
  * A node can be removed from a book if it is actually in a book and it either
  * is not a top-level page or is a top-level page with no children.
+ *
+ * @param Drupal\node\Node $node
+ *   The node to remove from the outline.
+ *
+ * @return bool
+ *   A Boolean indicating whether the node can be removed from the book.
  */
 function _book_node_is_removable($node) {
   return (!empty($node->book['bid']) && (($node->book['bid'] != $node->nid) || !$node->book['has_children']));
@@ -361,7 +373,7 @@ function book_block_save($delta = '', $edit = array()) {
 /**
  * Returns HTML for a link to a book title when used as a block title.
  *
- * @param $variables
+ * @param array $variables
  *   An associative array containing:
  *   - link: An array containing title, href and options for the link.
  *
@@ -748,7 +760,7 @@ function book_get_flat_menu($book_link) {
  * @param $tree
  *   A tree of menu links in an array.
  * @param $flat
- *   A flat array of the menu links from $tree.
+ *   A flat array of the menu links from $tree, passed by reference.
  *
  * @see book_get_flat_menu().
  */
@@ -1081,8 +1093,9 @@ function book_preprocess_block(&$variables) {
  * 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
+ * @param array $variables
+ *   An associative array containing the following key:
+ *   - book_menus
  *
  * @see book-all-books-block.tpl.php
  */
@@ -1098,8 +1111,9 @@ function template_preprocess_book_all_books_block(&$variables) {
 /**
  * Processes variables for book-navigation.tpl.php.
  *
- * The $variables array contains the following elements:
- * - book_link
+ * @param array $variables
+ *   An associative array containing the following key:
+ *   - book_link
  *
  * @see book-navigation.tpl.php
  */
@@ -1199,8 +1213,9 @@ 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 menu link ID values. Any link whose menu link ID is in
- *   this array will be excluded (along with its children).
+ *   (optional) An array of menu link ID values. Any link whose menu link ID is
+ *   in this array will be excluded (along with its children). Defaults to an
+ *   empty array.
  *
  * @return
  *   An array of (menu link ID, title) pairs for use as options for selecting a
@@ -1217,10 +1232,11 @@ function book_toc($bid, $depth_limit, $exclude = array()) {
 /**
  * Preprocesses variables for book-export-html.tpl.php.
  *
- * The $variables array contains the following elements:
- * - title
- * - contents
- * - depth
+ * @param array $variables
+ *   An associative array containing the following keys:
+ *   - title
+ *   - contents
+ *   - depth
  *
  * @see book-export-html.tpl.php
  */
@@ -1242,6 +1258,10 @@ function template_preprocess_book_export_html(&$variables) {
 /**
  * Processes variables for book-export-html.tpl.php.
  *
+ * @param array $variables
+ *   An associative array containing the following key:
+ *   - html_attributes
+ *
  * @see book-export-html.tpl.php
  */
 function template_process_book_export_html(&$variables) {
@@ -1294,7 +1314,8 @@ function book_export_traverse($tree, $visit_func) {
  * @param Drupal\node\Node $node
  *   The node that will be output.
  * @param $children
- *   All the rendered child nodes within the current node.
+ *   (optional) All the rendered child nodes within the current node. Defaults
+ *   to an empty string.
  *
  * @return
  *   The HTML generated for the given node.
@@ -1313,9 +1334,9 @@ function book_node_export(Node $node, $children = '') {
 /**
  * Processes variables for book-node-export-html.tpl.php.
  *
- * The $variables array contains the following elements:
- * - node
- * - children
+ * @param array $variables
+ *   An associative array containing the following keys:
+ *   - node
  *
  * @see book-node-export-html.tpl.php
  */
@@ -1327,6 +1348,12 @@ function template_preprocess_book_node_export_html(&$variables) {
 
 /**
  * Determines if a given node type is in the list of types allowed for books.
+ *
+ * @param string $type
+ *   A node type.
+ *
+ * @return bool
+ *   A Boolean TRUE if the node type can be included in books; otherwise, FALSE.
  */
 function book_type_is_allowed($type) {
   return in_array($type, config('book.settings')->get('allowed_types'));
@@ -1371,7 +1398,7 @@ function book_node_type_update($type) {
  *
  * @return
  *   A menu link, with the link translated for rendering and data added from the
- *   {book} table.
+ *   {book} table. FALSE if there is an error.
  */
 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(
diff --git a/core/modules/book/book.pages.inc b/core/modules/book/book.pages.inc
index 90b2192..212190a 100644
--- a/core/modules/book/book.pages.inc
+++ b/core/modules/book/book.pages.inc
@@ -12,6 +12,9 @@
 /**
  * Page callback: Prints a listing of all books.
  *
+ * @return string
+ *   A HTML-formatted string with the listing of all books content.
+ *
  * @see book_menu()
  */
 function book_render() {
@@ -43,6 +46,8 @@ function book_render() {
  *   A string representing the node and its children in the book hierarchy in a
  *   format determined by the $type parameter.
  *
+ * @throws \Symfony\Component\HttpKernel\Exception\NotFoundHttpException
+ *
  * @see book_menu()
  */
 function book_export($type, $nid) {
@@ -75,6 +80,9 @@ function book_export($type, $nid) {
  * @return
  *   A string containing HTML representing the node and its children in
  *   the book hierarchy.
+ *
+ * @throws \Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException
+ * @throws \Symfony\Component\HttpKernel\Exception\NotFoundHttpException
  */
 function book_export_html($nid) {
   if (user_access('access printer-friendly version')) {
@@ -100,6 +108,9 @@ function book_export_html($nid) {
  * @param Drupal\node\Node $node
  *   The book node for which to show the outline.
  *
+ * @return string
+ *   A HTML-formatted string with the outline form for a single node.
+ *
  * @see book_menu()
  */
 function book_outline(Node $node) {
diff --git a/core/modules/book/book.theme-rtl.css b/core/modules/book/book.theme-rtl.css
index 0fe891c..381a4cc 100644
--- a/core/modules/book/book.theme-rtl.css
+++ b/core/modules/book/book.theme-rtl.css
@@ -1,7 +1,6 @@
-
 /**
  * @file
- * RTL styling for the book module.
+ * Right-to-Left styling for the Book module.
  */
 
 /**
diff --git a/core/modules/book/book.theme.css b/core/modules/book/book.theme.css
index 9a807c8..f1da027 100644
--- a/core/modules/book/book.theme.css
+++ b/core/modules/book/book.theme.css
@@ -1,7 +1,6 @@
-
 /**
  * @file
- * Styling for the book module.
+ * Styling for the Book module.
  */
 
 /**
diff --git a/core/modules/book/lib/Drupal/book/Tests/BookTest.php b/core/modules/book/lib/Drupal/book/Tests/BookTest.php
index a1a88c4..c2f36a3 100644
--- a/core/modules/book/lib/Drupal/book/Tests/BookTest.php
+++ b/core/modules/book/lib/Drupal/book/Tests/BookTest.php
@@ -10,6 +10,9 @@
 use Drupal\node\Node;
 use Drupal\simpletest\WebTestBase;
 
+/**
+ * Tests the functionality of the Book module.
+ */
 class BookTest extends WebTestBase {
 
   /**
@@ -19,13 +22,32 @@ class BookTest extends WebTestBase {
    */
   public static $modules = array('book', 'block', 'node_access_test');
 
+  /**
+   * A book node.
+   *
+   * @var object
+   */
   protected $book;
-  // $book_author is a user with permission to create and edit books.
+
+  /**
+   * A user with permission to create and edit books.
+   *
+   * @var object
+   */
   protected $book_author;
-  // $web_user is a user with permission to view a book
-  // and access the printer-friendly version.
+
+  /**
+   * A user with permission to view a book and access printer-friendly version.
+   *
+   * @var object
+   */
   protected $web_user;
-  // $admin_user is a user with permission to create and edit books and to administer blocks.
+
+  /**
+   * A user with permission to create and edit books and to administer blocks.
+   *
+   * @var object
+   */
   protected $admin_user;
 
   public static function getInfo() {
@@ -49,7 +71,7 @@ function setUp() {
   }
 
   /**
-   * Create a new book with a page hierarchy.
+   * Creates a new book with a page hierarchy.
    */
   function createBook() {
     // Create new book.
@@ -80,7 +102,7 @@ function createBook() {
   }
 
   /**
-   * Test book functionality through node interfaces.
+   * Tests Book functionality through node interfaces.
    */
   function testBook() {
     // Create new book.
@@ -119,19 +141,19 @@ function testBook() {
   }
 
   /**
-   * Check the outline of sub-pages; previous, up, and next; and printer friendly version.
+   * Checks the outline of sub-pages; previous, up, and next; and printer friendly version.
    *
    * @param Drupal\node\Node $node
    *   Node to check.
    * @param $nodes
    *   Nodes that should be in outline.
    * @param $previous
-   *   Previous link node.
+   *   (optional) Previous link node. Defaults to FALSE.
    * @param $up
-   *   Up link node.
+   *   (optional) Up link node. Defaults to FALSE.
    * @param $next
-   *   Next link node.
-   * @param $breadcrumb
+   *   (optional) Next link node. Defaults to FALSE.
+   * @param array $breadcrumb
    *   The nodes that should be displayed in the breadcrumb.
    */
   function checkBookNode(Node $node, $nodes, $previous = FALSE, $up = FALSE, $next = FALSE, array $breadcrumb) {
@@ -187,9 +209,13 @@ function checkBookNode(Node $node, $nodes, $previous = FALSE, $up = FALSE, $next
   }
 
   /**
-   * Create a regular expression to check for the sub-nodes in the outline.
+   * Creates a regular expression to check for the sub-nodes in the outline.
+   *
+   * @param array $nodes
+   *   An array of Nodes to check in outline.
    *
-   * @param array $nodes Nodes to check in outline.
+   * @return string
+   *   A customized regular expression as a string.
    */
   function generateOutlinePattern($nodes) {
     $outline = '';
@@ -201,10 +227,12 @@ function generateOutlinePattern($nodes) {
   }
 
   /**
-   * Create book node.
+   * Creates a book node.
    *
-   * @param integer $book_nid Book node id or set to 'new' to create new book.
-   * @param integer $parent Parent book reference id.
+   * @param int|string $book_nid
+   *   Book node ID or set to 'new' to create new book.
+   * @param int|null $parent
+   *   (optional) Parent book reference id. Defaults to NULL.
    */
   function createBookNode($book_nid, $parent = NULL) {
     // $number does not use drupal_static as it should not be reset
@@ -305,7 +333,7 @@ function testBookNavigationBlock() {
   }
 
   /**
-   * Test the book navigation block when an access module is enabled.
+   * Tests the book navigation block when an access module is enabled.
    */
    function testNavigationBlockOnAccessModuleEnabled() {
      $this->drupalLogin($this->admin_user);
-- 
1.7.6.msysgit.0