Issue #1807688 by Albert Volkman, Lars Toomre: API docs fixes for Book module

7 files changed, 109 insertions, 37 deletions

diff --git a/modules/book/book-rtl.css b/modules/book/book-rtl.css
index f3a84c20e..40dff0e53 100644
--- a/modules/book/book-rtl.css
+++ b/modules/book/book-rtl.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Right-to-Left styling for the Book module.
+ */
 
 .book-navigation .menu {
   padding: 1em 3em 0 0;
diff --git a/modules/book/book.admin.inc b/modules/book/book.admin.inc
index 62c6e841a..cc3f08fc8 100644
--- a/modules/book/book.admin.inc
+++ b/modules/book/book.admin.inc
@@ -2,11 +2,16 @@
 
 /**
  * @file
- * Admin page callbacks for the book module.
+ * Administration page callbacks for the Book module.
  */
 
 /**
  * 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() {
   $rows = array();
@@ -53,6 +58,8 @@ function book_admin_settings() {
 
 /**
  * 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'];
@@ -149,7 +156,7 @@ function book_admin_edit_submit($form, &$form_state) {
  * @param $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()
  */
@@ -184,10 +191,10 @@ function _book_admin_table($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()
  */
diff --git a/modules/book/book.css b/modules/book/book.css
index a8d2136df..00e379ee0 100644
--- a/modules/book/book.css
+++ b/modules/book/book.css
@@ -1,3 +1,7 @@
+ /**
+  * @file
+  * Styling for the Book module.
+  */
 
 .book-navigation .menu {
   border-top: 1px solid #888;
diff --git a/modules/book/book.js b/modules/book/book.js
index 0853e8ecb..64f4aee68 100644
--- a/modules/book/book.js
+++ b/modules/book/book.js
@@ -3,7 +3,6 @@
  * Javascript behaviors for the Book module.
  */
 
-
 (function ($) {
 
 Drupal.behaviors.bookFieldsetSummaries = {
diff --git a/modules/book/book.module b/modules/book/book.module
index 1fb0c0b11..71b89945e 100644
--- a/modules/book/book.module
+++ b/modules/book/book.module
@@ -221,6 +221,9 @@ function _book_outline_remove_access($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 $node
+ *   The node to remove from the outline.
  */
 function _book_node_is_removable($node) {
   return (!empty($node->book['bid']) && (($node->book['bid'] != $node->nid) || !$node->book['has_children']));
@@ -734,7 +737,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().
  */
@@ -1062,8 +1065,9 @@ function _book_link_defaults($nid) {
  * 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 $variables
+ *   An associative array containing the following key:
+ *   - book_menus
  *
  * @see book-all-books-block.tpl.php
  */
@@ -1079,8 +1083,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 $variables
+ *   An associative array containing the following key:
+ *   - book_link
  *
  * @see book-navigation.tpl.php
  */
@@ -1151,8 +1156,9 @@ 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 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.
  * @param $depth_limit
  *   Any link deeper than this value will be excluded (along with its children).
  */
@@ -1198,10 +1204,11 @@ function book_toc($bid, $depth_limit, $exclude = array()) {
 /**
  * Processes variables for book-export-html.tpl.php.
  *
- * The $variables array contains the following elements:
- * - title
- * - contents
- * - depth
+ * @param $variables
+ *   An associative array containing the following keys:
+ *   - title
+ *   - contents
+ *   - depth
  *
  * @see book-export-html.tpl.php
  */
@@ -1261,7 +1268,8 @@ function book_export_traverse($tree, $visit_func) {
  * @param $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.
@@ -1280,9 +1288,10 @@ function book_node_export($node, $children = '') {
 /**
  * Processes variables for book-node-export-html.tpl.php.
  *
- * The $variables array contains the following elements:
- * - node
- * - children
+ * @param $variables
+ *   An associative array containing the following keys:
+ *   - node
+ *   - children
  *
  * @see book-node-export-html.tpl.php
  */
@@ -1294,6 +1303,12 @@ function template_preprocess_book_node_export_html(&$variables) {
 
 /**
  * Determine if a given node type is in the list of types allowed for books.
+ *
+ * @param $type
+ *   A node type.
+ *
+ * @return
+ *   A Boolean TRUE if the node type can be included in books; otherwise, FALSE.
  */
 function book_type_is_allowed($type) {
   return in_array($type, variable_get('book_allowed_types', array('book')));
@@ -1336,7 +1351,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/modules/book/book.pages.inc b/modules/book/book.pages.inc
index 583eb7a81..19f61158c 100644
--- a/modules/book/book.pages.inc
+++ b/modules/book/book.pages.inc
@@ -7,6 +7,11 @@
 
 /**
  * Menu 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() {
   $book_list = array();
@@ -36,6 +41,8 @@ function book_render() {
  * @return
  *   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);
@@ -91,6 +98,11 @@ function book_export_html($nid) {
  *
  * @param $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) {
   drupal_set_title($node->title);
diff --git a/modules/book/book.test b/modules/book/book.test
index 0006d0b0d..71dc6fe61 100644
--- a/modules/book/book.test
+++ b/modules/book/book.test
@@ -5,14 +5,37 @@
  * Tests for book.module.
  */
 
+/**
+ * Tests the functionality of the Book module.
+ */
 class BookTestCase extends DrupalWebTestCase {
+
+  /**
+   * 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() {
@@ -36,7 +59,7 @@ class BookTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Create a new book with a page hierarchy.
+   * Creates a new book with a page hierarchy.
    */
   function createBook() {
     // Create new book.
@@ -67,7 +90,7 @@ class BookTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Test book functionality through node interfaces.
+   * Tests book functionality through node interfaces.
    */
   function testBook() {
     // Create new book.
@@ -106,18 +129,20 @@ class BookTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Check the outline of sub-pages; previous, up, and next; and printer friendly version.
+   * Checks the outline of sub-pages; previous, up, and next.
+   *
+   * Also checks the printer friendly version of the outline.
    *
    * @param $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.
+   *   (optional) Next link node. Defaults to FALSE.
    * @param $breadcrumb
    *   The nodes that should be displayed in the breadcrumb.
    */
@@ -174,9 +199,13 @@ class BookTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * 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
+   *   A regular expression that locates sub-nodes of the outline.
    */
   function generateOutlinePattern($nodes) {
     $outline = '';
@@ -188,10 +217,12 @@ class BookTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * 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 $book_nid
+   *   A book node ID or set to 'new' to create a new book.
+   * @param $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
@@ -292,7 +323,7 @@ class BookTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * 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);