From f0da6c528d46d869cec8f1a54572123ce070e713 Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Thu, 4 Oct 2012 09:41:38 -0700
Subject: [PATCH] Issue #1313980 by Lars Toomre: Fix up some docs in node
 module

---
 core/modules/node/content_types.inc | 12 ++++
 core/modules/node/node.admin.inc    | 59 ++++++++++++------
 core/modules/node/node.install      |  4 +-
 core/modules/node/node.module       | 92 +++++++++++++++++++++++++----
 core/modules/node/node.pages.inc    | 46 ++++++++++++++-
 5 files changed, 178 insertions(+), 35 deletions(-)

diff --git a/core/modules/node/content_types.inc b/core/modules/node/content_types.inc
index 355a022bed2..7388ee951b3 100644
--- a/core/modules/node/content_types.inc
+++ b/core/modules/node/content_types.inc
@@ -8,6 +8,9 @@
 /**
  * Page callback: Displays the content type admin overview page.
  *
+ * @return array
+ *   An array as expected by drupal_render().
+ *
  * @see node_menu()
  */
 function node_overview_types() {
@@ -63,6 +66,9 @@ function node_overview_types() {
  *   - type: An object containing the 'type' (machine name) and 'description' of
  *     the content type.
  *
+ * @return string
+ *   An HTML-formatted string of the description for this node type.
+ *
  * @ingroup themeable
  */
 function theme_node_admin_overview($variables) {
@@ -278,6 +284,12 @@ function node_type_form($form, &$form_state, $type = NULL) {
 
 /**
  * Helper function for teaser length choices.
+ *
+ * @param int $length
+ *   An integer representing the desired length of the teaser string.
+ *
+ * @return string
+ *   A string that reprents the teaser length options.
  */
 function _node_characters($length) {
   return ($length == 0) ? t('Unlimited') : format_plural($length, '1 character', '@count characters');
diff --git a/core/modules/node/node.admin.inc b/core/modules/node/node.admin.inc
index f77ec7dc37e..2ca2d3e1859 100644
--- a/core/modules/node/node.admin.inc
+++ b/core/modules/node/node.admin.inc
@@ -10,8 +10,11 @@ use Drupal\Core\Database\Query\SelectInterface;
 /**
  * Page callback: Form constructor for the permission rebuild confirmation form.
  *
- * @see node_menu()
+ * @return array
+ *   An array as expected by drupal_render().
+ *
  * @see node_configure_rebuild_confirm_submit()
+ * @see node_menu()
  */
 function node_configure_rebuild_confirm() {
   return confirm_form(array(), t('Are you sure you want to rebuild the permissions on site content?'),
@@ -73,7 +76,7 @@ function node_node_operations() {
  * Lists node administration filters that can be applied.
  *
  * @return
- *   Associative array of filters.
+ *   An associative array of filters.
  */
 function node_filters() {
   // Regular filters
@@ -124,7 +127,7 @@ function node_filters() {
 /**
  * Applies filters for the node administration overview based on session.
  *
- * @param $query
+ * @param Drupal\Core\Database\Query\SelectInterface $query
  *   A SelectQuery to which the filters should be applied.
  */
 function node_build_filter_query(SelectInterface $query) {
@@ -145,14 +148,15 @@ function node_build_filter_query(SelectInterface $query) {
 }
 
 /**
- * Returns the node administration filters form object to node_admin_content().
+ * Returns the node administration filters form array to node_admin_content().
  *
- * @see node_multiple_delete_confirm()
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes()
  * @see node_admin_nodes_submit()
  * @see node_admin_nodes_validate()
  * @see node_filter_form_submit()
+ * @see node_multiple_delete_confirm()
+ * @see node_multiple_delete_confirm_submit()
+ *
  * @ingroup forms
  */
 function node_filter_form() {
@@ -231,12 +235,12 @@ function node_filter_form() {
  * Form submission handler for node_filter_form().
  *
  * @see node_admin_content()
- * @see node_multiple_delete_confirm()
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes()
  * @see node_admin_nodes_submit()
  * @see node_admin_nodes_validate()
  * @see node_filter_form()
+ * @see node_multiple_delete_confirm()
+ * @see node_multiple_delete_confirm_submit()
  */
 function node_filter_form_submit($form, &$form_state) {
   $filters = node_filters();
@@ -310,6 +314,9 @@ function node_mass_update($nodes, $updates) {
  * @param $updates
  *   Associative array of updates.
  *
+ * @return object
+ *   An updated node object.
+ *
  * @see node_mass_update()
  */
 function _node_mass_update_helper($nid, $updates) {
@@ -325,6 +332,13 @@ function _node_mass_update_helper($nid, $updates) {
 
 /**
  * Executes a batch operation for node_mass_update().
+ *
+ * @param array $nodes
+ *   An array of node IDs.
+ * @param array $updates
+ *   Associative array of updates.
+ * @param array $context
+ *   An array of contextual key/values.
  */
 function _node_mass_update_batch_process($nodes, $updates, &$context) {
   if (!isset($context['sandbox']['progress'])) {
@@ -356,6 +370,14 @@ function _node_mass_update_batch_process($nodes, $updates, &$context) {
 
 /**
  * Reports the 'finished' status of batch operation for node_mass_update().
+ *
+ * @param bool $success
+ *   A boolean indicating whether the batch mass update operation successfully
+ *   concluded.
+ * @param int $results
+ *   The number of nodes updated via the batch mode process.
+ * @param array $operations
+ *   An array of function calls (not used in this function).
  */
 function _node_mass_update_batch_finished($success, $results, $operations) {
   if ($success) {
@@ -372,14 +394,14 @@ function _node_mass_update_batch_finished($success, $results, $operations) {
 /**
  * Page callback: Form constructor for the content administration form.
  *
- * @see node_multiple_delete_confirm()
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes()
  * @see node_admin_nodes_submit()
  * @see node_admin_nodes_validate()
  * @see node_filter_form()
  * @see node_filter_form_submit()
  * @see node_menu()
+ * @see node_multiple_delete_confirm()
+ * @see node_multiple_delete_confirm_submit()
  */
 function node_admin_content($form, $form_state) {
   if (isset($form_state['values']['operation']) && $form_state['values']['operation'] == 'delete') {
@@ -395,12 +417,13 @@ function node_admin_content($form, $form_state) {
 /**
  * Returns the admin form object to node_admin_content().
  *
- * @see node_multiple_delete_confirm()
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes_submit()
  * @see node_admin_nodes_validate()
  * @see node_filter_form()
  * @see node_filter_form_submit()
+ * @see node_multiple_delete_confirm()
+ * @see node_multiple_delete_confirm_submit()
+ *
  * @ingroup forms
  */
 function node_admin_nodes() {
@@ -592,12 +615,12 @@ function node_admin_nodes() {
  * Checks if any nodes have been selected to perform the chosen
  * 'Update option' on.
  *
- * @see node_multiple_delete_confirm()
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes()
  * @see node_admin_nodes_submit()
  * @see node_filter_form()
  * @see node_filter_form_submit()
+ * @see node_multiple_delete_confirm()
+ * @see node_multiple_delete_confirm_submit()
  */
 function node_admin_nodes_validate($form, &$form_state) {
   // Error if there are no items to select.
@@ -611,12 +634,12 @@ function node_admin_nodes_validate($form, &$form_state) {
  *
  * Executes the chosen 'Update option' on the selected nodes.
  *
- * @see node_multiple_delete_confirm()
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes()
  * @see node_admin_nodes_validate()
  * @see node_filter_form()
  * @see node_filter_form_submit()
+ * @see node_multiple_delete_confirm()
+ * @see node_multiple_delete_confirm_submit()
  */
 function node_admin_nodes_submit($form, &$form_state) {
   $operations = module_invoke_all('node_operations');
@@ -645,12 +668,12 @@ function node_admin_nodes_submit($form, &$form_state) {
 /**
  * Multiple node deletion confirmation form for node_admin_content().
  *
- * @see node_multiple_delete_confirm_submit()
  * @see node_admin_nodes()
  * @see node_admin_nodes_submit()
  * @see node_admin_nodes_validate()
  * @see node_filter_form()
  * @see node_filter_form_submit()
+ * @see node_multiple_delete_confirm_submit()
  */
 function node_multiple_delete_confirm($form, &$form_state, $nodes) {
   $form['nodes'] = array('#prefix' => '<ul>', '#suffix' => '</ul>', '#tree' => TRUE);
@@ -678,12 +701,12 @@ function node_multiple_delete_confirm($form, &$form_state, $nodes) {
 /**
  * Form submission handler for node_multiple_delete_confirm().
  *
- * @see node_multiple_delete_confirm()
  * @see node_admin_nodes()
  * @see node_admin_nodes_submit()
  * @see node_admin_nodes_validate()
  * @see node_filter_form()
  * @see node_filter_form_submit()
+ * @see node_multiple_delete_confirm()
  */
 function node_multiple_delete_confirm_submit($form, &$form_state) {
   if ($form_state['values']['confirm']) {
diff --git a/core/modules/node/node.install b/core/modules/node/node.install
index 47b4345a129..eb9094b3653 100644
--- a/core/modules/node/node.install
+++ b/core/modules/node/node.install
@@ -454,6 +454,9 @@ function node_install() {
 
 /**
  * Implements hook_uninstall().
+ *
+ * @see node_ranking()
+ * @see _node_rankings()
  */
 function node_uninstall() {
   // Delete node type variables.
@@ -473,7 +476,6 @@ function node_uninstall() {
   }
 
   // Delete node search ranking variables.
-  // @see node_ranking(), _node_rankings()
   variable_del('node_rank_relevance');
   variable_del('node_rank_sticky');
   variable_del('node_rank_promote');
diff --git a/core/modules/node/node.module b/core/modules/node/node.module
index 175bf475371..2dd1b57ca14 100644
--- a/core/modules/node/node.module
+++ b/core/modules/node/node.module
@@ -287,6 +287,9 @@ function node_field_display_node_alter(&$display, $context) {
  *
  * @param Drupal\node\Node $node
  *   A node entity.
+ *
+ * @return array
+ *   An array with 'path' as the key and Node ID as its value.
  */
 function node_uri(Node $node) {
   return array(
@@ -360,6 +363,13 @@ function node_tag_new(Node $node) {
 
 /**
  * Retrieves the timestamp for the current user's last view of a specified node.
+ *
+ * @param int $nid
+ *   A node ID.
+ *
+ * @return int
+ *   If a node has been previously viewed by the user, the timestamp in seconds
+ *   of when the last view occurred; otherwise, zero.
  */
 function node_last_viewed($nid) {
   global $user;
@@ -411,6 +421,7 @@ function node_mark($nid, $timestamp) {
  * @return
  *   An array of node types, as objects, keyed by the type.
  *
+ * @see _node_types_build()
  * @see node_type_load()
  */
 function node_type_get_types() {
@@ -445,6 +456,8 @@ function node_type_get_base($type) {
  *
  * @return
  *   An array of node type labels, keyed by the node type name.
+ *
+ * @see _node_types_build()
  */
 function node_type_get_names() {
   return _node_types_build()->names;
@@ -784,7 +797,8 @@ function node_type_update_nodes($old_type, $type) {
  * until node_types_rebuild() is called.
  *
  * @param $rebuild
- *  TRUE to rebuild node types. Equivalent to calling node_types_rebuild().
+ *  (optional) TRUE to rebuild node types. Equivalent to calling
+ *  node_types_rebuild(). Defaults to FALSE.
  *
  * @return
  *   An object with two properties:
@@ -897,6 +911,8 @@ function node_type_cache_reset() {
  *
  * @return
  *   A node type object, with missing values in $info set to their defaults.
+ *
+ * @see hook_node_ifo()
  */
 function node_type_set_defaults($info = array()) {
   $info = (array) $info;
@@ -999,7 +1015,8 @@ function node_hook($type, $hook) {
  * @param $hook
  *   A string containing the name of the hook.
  * @param $a2, $a3, $a4
- *   Arguments to pass on to the hook, after the $node argument.
+ *   (optional) Arguments to pass on to the hook, after the $node argument. All
+ *   default to NULL.
  *
  * @return
  *   The returned value of the invoked hook.
@@ -1020,7 +1037,8 @@ function node_invoke($node, $hook, $a2 = NULL, $a3 = NULL, $a4 = NULL) {
  * @param array $nids
  *   (optional) An array of entity IDs. If omitted, all entities are loaded.
  * @param bool $reset
- *   (optional) Whether to reset the internal node_load() cache.
+ *   (optional) Whether to reset the internal node_load() cache.  Defaults to
+ *   FALSE.
  *
  * @return array
  *   An array of node entities indexed by nid.
@@ -1038,7 +1056,8 @@ function node_load_multiple(array $nids = NULL, $reset = FALSE) {
  * @param int $nid
  *   The node ID.
  * @param bool $reset
- *   (optional) Whether to reset the node_load_multiple() cache.
+ *   (optional) Whether to reset the node_load_multiple() cache. Defaults to
+ *   FALSE.
  *
  * @return Drupal\node\Node|false
  *   A fully-populated node entity, or FALSE if the node is not found.
@@ -1062,6 +1081,12 @@ function node_revision_load($vid = NULL) {
 
 /**
  * Prepares a node for saving by populating the author and creation date.
+ *
+ * @param object $node
+ *   A node object.
+ *
+ * @return object
+ *   An updated node object.
  */
 function node_submit($node) {
   global $user;
@@ -1129,7 +1154,7 @@ function node_delete_multiple($nids) {
  *   The revision ID to delete.
  *
  * @return
- *   TRUE if the revision deletion was successful.
+ *   TRUE if the revision deletion was successful; otherwise, FALSE.
  */
 function node_revision_delete($revision_id) {
   if ($revision = node_revision_load($revision_id)) {
@@ -1295,7 +1320,7 @@ function node_build_content(Node $node, $view_mode = 'full', $langcode = NULL) {
  *   A node entity.
  * @param $message
  *   (optional) A flag which sets a page title relevant to the revision being
- *   viewed.
+ *   viewed.  Default is FALSE.
  *
  * @return
  *   A $page element suitable for use by drupal_render().
@@ -1764,10 +1789,11 @@ function theme_node_search_admin($variables) {
  * @param object $account
  *   (optional) A user object representing the user for whom the operation is
  *   to be performed. Determines access for a user other than the current user.
+ *   Defaults to NULL.
  * @param $langcode
  *   (optional) Language code for the variant of the node. Different language
  *   variants might have different permissions associated. If NULL, the
- *   original langcode of the node is used.
+ *   original langcode of the node is used. Defaults to NULL.
  *
  * @return
  *   TRUE if the operation may be performed, FALSE otherwise.
@@ -2050,6 +2076,9 @@ function node_menu_local_tasks_alter(&$data, $router_item, $root_path) {
  * @param $type
  *   The node type object.
  *
+ * @return string
+ *   An unsanitized string that is the title of the node type edit form.
+ *
  * @see node_menu()
  */
 function node_type_page_title($type) {
@@ -2062,6 +2091,9 @@ function node_type_page_title($type) {
  * @param Drupal\node\Node $node
  *   The node entity.
  *
+ * @return
+ *   An unsanitized string that is the title of the node.
+ *
  * @see node_menu()
  */
 function node_page_title(Node $node) {
@@ -2086,6 +2118,9 @@ function node_last_changed($nid) {
  *
  * @param Drupal\node\Node $node
  *   The node entity.
+ *
+ * @return
+ *   An associative array keyed by node revision number.
  */
 function node_revision_list(Node $node) {
   $revisions = array();
@@ -2440,6 +2475,9 @@ function node_block_list_alter(&$blocks) {
  *   @link http://cyber.law.harvard.edu/rss/rss.html RSS 2.0 Specification. @endlink
  *   The link should be an absolute URL.
  *
+ * @return Symfony\Component\HttpFoundation\Response
+ *   A response object.
+ *
  * @see node_menu()
  */
 function node_feed($nids = FALSE, $channel = array()) {
@@ -2545,6 +2583,9 @@ function node_view_multiple($nodes, $view_mode = 'teaser', $weight = 0, $langcod
 /**
  * Page callback: Generates a listing of promoted nodes.
  *
+ * @return array
+ *   An array in the format expected by drupal_render().
+ *
  * @see node_menu()
  */
 function node_page_default() {
@@ -2601,6 +2642,9 @@ function node_page_default() {
  * @param Drupal\node\Node $node
  *   The node entity.
  *
+ * @return
+ *   A page array suitable for use by drupal_render().
+ *
  * @see node_menu()
  */
 function node_page_view(Node $node) {
@@ -2908,10 +2952,11 @@ function node_form_system_themes_admin_form_submit($form, &$form_state) {
  * @param $account
  *   (optional) A user object representing the user for whom the operation is to
  *   be performed. Determines access for a user other than the current user.
+ *   Defaults to NULL.
  * @param $langcode
  *   (optional) Language code for the variant of the node. Different language
  *   variants might have different permissions associated. If NULL, the
- *   original langcode of the node is used.
+ *   original langcode of the node is used. Defaults to NULL.
  *
  * @return
  *   TRUE if the operation may be performed, FALSE otherwise.
@@ -3123,7 +3168,7 @@ function node_permissions_get_configured_types() {
  *   The operation that the user is trying to perform.
  * @param $account
  *   (optional) The user object for the user performing the operation. If
- *   omitted, the current user is used.
+ *   omitted, the current user is used.  Defaults to NULL.
  *
  * @return
  *   An associative array in which the keys are realms, and the values are
@@ -3157,7 +3202,7 @@ function node_access_grants($op, $account = NULL) {
  *
  * @param $account
  *   (optional) The user object for the user whose access is being checked. If
- *   omitted, the current user is used.
+ *   omitted, the current user is used. Defaults to NULL.
  *
  * @return
  *   TRUE if 'view' access to all nodes is granted, FALSE otherwise.
@@ -3242,6 +3287,9 @@ function node_query_entity_field_access_alter(AlterableInterface $query) {
  *   Either 'node' or 'entity' depending on what sort of query it is. See
  *   node_query_node_access_alter() and node_query_entity_field_access_alter()
  *   for more.
+ *
+ * @see node_query_node_access_alter()
+ * @see node_query_entity_field_access_alter()
  */
 function _node_query_node_access_alter($query, $type) {
   global $user;
@@ -3420,11 +3468,12 @@ function node_access_acquire_grants(Node $node, $delete = TRUE) {
  *   is a module-defined id to define grant privileges. each grant_* field
  *   is a boolean value.
  * @param $realm
- *   (optional) If provided, read/write grants for that realm only.
+ *   (optional) If provided, read/write grants for that realm only. Defaults to
+ *   NULL.
  * @param $delete
  *   (optional) If false, does not delete records. This is only for optimization
  *   purposes, and assumes the caller has already performed a mass delete of
- *   some form.
+ *   some form. Defaults to TRUE.
  */
 function _node_access_write_grants(Node $node, $grants, $realm = NULL, $delete = TRUE) {
   if ($delete) {
@@ -3499,7 +3548,8 @@ function node_access_needs_rebuild($rebuild = NULL) {
  *   has a large number of nodes). hook_update_N() and any form submit handler
  *   are safe contexts to use the 'batch mode'. Less decidable cases (such as
  *   calls from hook_user(), hook_taxonomy(), etc.) might consider using the
- *   non-batch mode.
+ *   non-batch mode. Defaults to FALSE.
+ *
  * @see node_access_needs_rebuild()
  */
 function node_access_rebuild($batch_mode = FALSE) {
@@ -3559,6 +3609,9 @@ function node_access_rebuild($batch_mode = FALSE) {
  * This is a multistep operation : we go through all nodes by packs of 20.
  * The batch processing engine interrupts processing and sends progress
  * feedback after 1 second execution time.
+ *
+ * @param array $context
+ *   An array of contextual key/value information for rebuild batch process.
  */
 function _node_access_rebuild_batch_operation(&$context) {
   if (empty($context['sandbox'])) {
@@ -3590,6 +3643,13 @@ function _node_access_rebuild_batch_operation(&$context) {
 
 /**
  * Post-processing for node_access_rebuild_batch.
+ *
+ * @param bool $success
+ *   A boolean indicating whether the re-build process has completed.
+ * @param array $results
+ *   An array of results information.
+ * @param array $operations
+ *   An array of function calls (not used in this function).
  */
 function _node_access_rebuild_batch_finished($success, $results, $operations) {
   if ($success) {
@@ -3913,6 +3973,12 @@ function node_assign_owner_action_submit($form, $form_state) {
 
 /**
  * Generates settings form for node_unpublish_by_keyword_action().
+ *
+ * @param array $context
+ *   Array of additional information about what triggered this action.
+ *
+ * @return array
+ *   A form array.
  */
 function node_unpublish_by_keyword_action_form($context) {
   $form['keywords'] = array(
diff --git a/core/modules/node/node.pages.inc b/core/modules/node/node.pages.inc
index 12437e162a1..1780fb961b2 100644
--- a/core/modules/node/node.pages.inc
+++ b/core/modules/node/node.pages.inc
@@ -14,6 +14,12 @@ use Drupal\node\Node;
 /**
  * Page callback: Presents the node editing form.
  *
+ * @param object $node
+ *   A node object.
+ *
+ * @return array
+ *   A form array as expected by drupal_render().
+ *
  * @see node_menu()
  */
 function node_page_edit($node) {
@@ -26,6 +32,11 @@ function node_page_edit($node) {
  *
  * Redirects to node/add/[type] if only one content type is available.
  *
+ * @return array
+ *   A render array for a list of the node types that can be added; however, if
+ *   there is only one node type defined for the site, the function redirects
+ *   to the node add page for that one node type and does not return at all.
+ *
  * @see node_menu()
  */
 function node_add_page() {
@@ -51,7 +62,11 @@ function node_add_page() {
  *   An associative array containing:
  *   - content: An array of content types.
  *
+ * @return string
+ *   An HTML-formatted string.
+ *
  * @see node_add_page()
+ *
  * @ingroup themeable
  */
 function theme_node_add_list($variables) {
@@ -79,8 +94,8 @@ function theme_node_add_list($variables) {
  * @param $node_type
  *   The node type object for the submitted node.
  *
- * @return
- *   Returns a node submission form.
+ * @return array
+ *   A node submission form.
  *
  * @see node_menu()
  */
@@ -107,7 +122,7 @@ function node_add($node_type) {
  *   The node to preview.
  *
  * @return
- *   Themed node preview.
+ *   An HTML-formatted string of a node preview.
  *
  * @see node_form_build_preview()
  */
@@ -155,6 +170,7 @@ function node_preview(Node $node) {
  *   - node: The node entity which is being previewed.
  *
  * @see NodeFormController::preview()
+ *
  * @ingroup themeable
  */
 function theme_node_preview($variables) {
@@ -187,6 +203,12 @@ function theme_node_preview($variables) {
 /**
  * Page callback: Form constructor for node deletion confirmation form.
  *
+ * @param object $node
+ *   A node object.
+ *
+ * @return array
+ *   A form array.
+ *
  * @see node_menu()
  */
 function node_delete_confirm($form, &$form_state, $node) {
@@ -218,6 +240,12 @@ function node_delete_confirm_submit($form, &$form_state) {
 /**
  * Page callback: Generates an overview table of older revisions of a node.
  *
+ * @param object $node
+ *   A node object.
+ *
+ * @return array
+ *   An array as expected by drupal_render().
+ *
  * @see node_menu()
  */
 function node_revision_overview($node) {
@@ -276,6 +304,12 @@ function node_revision_overview($node) {
  *
  * This form prevents against CSRF attacks.
  *
+ * @param int $node_revision
+ *   The node revision ID.
+ *
+ * @return array
+ *   An array as expected by drupal_render().
+ *
  * @see node_menu()
  * @see node_revision_revert_confirm_submit()
  */
@@ -311,6 +345,12 @@ function node_revision_revert_confirm_submit($form, &$form_state) {
  *
  * This form prevents against CSRF attacks.
  *
+ * @param $node_revision
+ *   The node revision ID.
+ *
+ * @return
+ *   An array as expected by drupal_render().
+ *
  * @see node_menu()
  * @see node_revision_delete_confirm_submit()
  */