1 files changed, 17 insertions, 6 deletions
diff --git a/modules/book/book.module b/modules/book/book.module
index 6612ea38b..e034222e9 100644
--- a/modules/book/book.module
+++ b/modules/book/book.module
@@ -359,12 +359,13 @@ function book_outline_submit($form_id, $form_values) {
  * representing the path in the book tree from the root to the
  * parent of the given node.
  *
- * @param node - a book node object for which to compute the path
- *
- * @return - an array of book node objects representing the path of
- * nodes root to parent of the given node. Returns an empty array if
- * the node does not exist or is not part of a book hierarchy.
+ * @param $node
+ *   A book node object for which to compute the path.
  *
+ * @return
+ *   An array of book node objects representing the path nodes root to
+ *   parent of the given node. Returns an empty array if the node does
+ *   not exist or is not part of a book hierarchy.
  */
 function book_location($node, $nodes = array()) {
   $parent = db_fetch_object(db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.nid = %d'), $node->parent));
@@ -376,7 +377,17 @@ function book_location($node, $nodes = array()) {
 }
 
 /**
- * Accumulates the nodes up to the root of the book from the given node in the $nodes array.
+ * Given a node, this function returns an array of 'book node' objects
+ * representing the path in the book tree from the given node down to
+ * the last sibling of it.
+ *
+ * @param $node
+ *   A book node object where the path starts.
+ *
+ * @return
+ *   An array of book node objects representing the path nodes from the
+ *   given node. Returns an empty array if the node does not exist or
+ *   is not part of a book hierarchy or there are no siblings.
  */
 function book_location_down($node, $nodes = array()) {
   $last_direct_child = db_fetch_object(db_query(db_rewrite_sql('SELECT n.nid, n.title, b.parent, b.weight FROM {node} n INNER JOIN {book} b ON n.vid = b.vid WHERE n.status = 1 AND b.parent = %d ORDER BY b.weight DESC, n.title DESC'), $node->nid));