Skip to content

GitLab

Commit c8e431a4 authored by jhodgdon's avatar jhodgdon
Browse files

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

parent 7abbba0b
Hide whitespace changes
Inline Side-by-side
Showing with 103 additions and 45 deletions
core/modules/book/book.admin.css
View file @ c8e431a4
/**
* @file
* Admin styles for book module.
* Administration styles for the Book module.
*/
/**
......
core/modules/book/book.admin.inc
View file @ c8e431a4
......@@ -2,7 +2,7 @@
/**
* @file
* Admin page callbacks for the book module.
* Administration page callbacks for the Book module.
*/
use Drupal\node\Plugin\Core\Entity\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.
*
......
core/modules/book/book.install
View file @ c8e431a4
......@@ -88,7 +88,7 @@ function book_schema() {
}
/**
* Move book settings from variables to config.
* Move the Book module settings from variables to config.
*
* @ingroup config_upgrade
*/
......
core/modules/book/book.js
View file @ c8e431a4
......@@ -3,7 +3,6 @@
* Javascript behaviors for the Book module.
*/
(function ($) {
"use strict";
......
core/modules/book/book.module
View file @ c8e431a4
......@@ -227,6 +227,9 @@ 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.
*/
function _book_node_is_removable($node) {
return (!empty($node->book['bid']) && (($node->book['bid'] != $node->nid) || !$node->book['has_children']));
......@@ -629,7 +632,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().
*/
......@@ -962,8 +965,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
*/
......@@ -979,8 +983,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
*/
......@@ -1081,8 +1086,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
......@@ -1099,10 +1105,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
*/
......@@ -1168,7 +1175,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.
......@@ -1187,9 +1195,10 @@ 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
* - children
*
* @see book-node-export-html.tpl.php
*/
......@@ -1201,6 +1210,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'));
......@@ -1245,7 +1260,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(
......
core/modules/book/book.pages.inc
View file @ c8e431a4
......@@ -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) {
......
core/modules/book/book.theme-rtl.css
View file @ c8e431a4
/**
* @file
* RTL styling for the book module.
* Right-to-Left styling for the Book module.
*/
/**
......
core/modules/book/book.theme.css
View file @ c8e431a4
/**
* @file
* Styling for the book module.
* Styling for the Book module.
*/
/**
......
core/modules/book/lib/Drupal/book/Tests/BookTest.php
View file @ c8e431a4
......@@ -10,6 +10,9 @@
use Drupal\node\Plugin\Core\Entity\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,21 @@ 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.
*
* Also checks the printer friendly version of the outline.
*
* @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 +211,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 regular expression that locates sub-nodes of the outline.
*/
function generateOutlinePattern($nodes) {
$outline = '';
......@@ -201,10 +229,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
* A book node ID or set to 'new' to create a 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 +335,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);
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment