From 21a5d3affff0fda514f3143be222244443f8dde4 Mon Sep 17 00:00:00 2001
From: Bradley M. Froehle <bfroehle@math.berkeley.edu>
Date: Sat, 13 Nov 2010 12:20:53 -0800
Subject: [PATCH] #963656 follow-up by agentrickard, bfroehle: Improve documentation for {node_access} and node_access_view_all_nodes()

---
 modules/node/node.api.php |   36 ++++++++++++++++++++++++++++++++++++
 modules/node/node.module  |   10 +---------
 2 files changed, 37 insertions(+), 9 deletions(-)

diff --git modules/node/node.api.php modules/node/node.api.php
index 41dcdca..c6f24c7 100644
--- modules/node/node.api.php
+++ modules/node/node.api.php
@@ -143,6 +143,42 @@
  * module's responsibility to provide appropriate realms to limit access to
  * unpublished content.
  *
+ * Node access records are stored in the {node_access} table and define which
+ * grants are required to access a node.  An entry in the {node_access} table
+ * with node ID 0 corresponds to a global grant for the view operation.  It
+ * has no effect for other other operations like edit and delete.  If no node
+ * access modules are present, the core node module provides this global view
+ * permission for grant ID 0 and realm 'all'.
+ *
+ * Node access modules can replicate this behavior by providing their own
+ * conditional grant for an entry of {node_access} corresponding to node ID 0.
+ * For example, a module could create a record in {node_access} with:
+ * @code
+ * $record = array(
+ *   'nid' => 0,
+ *   'gid' => 888,
+ *   'realm' => 'example_realm',
+ *   'grant_view' => 1,
+ *   'grant_update' => 0,
+ *   'grant_delete' => 0,
+ * );
+ * drupal_write_record('node_access', $record);
+ * @endcode
+ * And grant the view access by returning the following array in
+ * hook_node_grants():
+ * @code
+ * if ($op == 'view') {
+ *   $grants['example_realm'] = array(888);
+ * }
+ * @endcode
+ *
+ * Beware that node_access_rebuild() function will erase any node ID 0 entry
+ * when it is called, as there is currently no hook to generate node ID 0
+ * grants.  Module developers are responsible for ensuring these gloabl view
+ * grants are restored after node_access_rebuild() is called.
+ *
+ * @see node_access_rebuild()
+ *
  * @param $account
  *   The user object whose grants are requested.
  * @param $op
diff --git modules/node/node.module modules/node/node.module
index 252d722..468f5d9 100644
--- modules/node/node.module
+++ modules/node/node.module
@@ -3008,15 +3008,7 @@ function node_access_grants($op, $account = NULL) {
  * Determines whether the user has a global viewing grant for all nodes.
  *
  * Checks to see whether any module grants 'view' for nid = 0. The node module
- * provides this record if no node access modules are enabled. Other modules
- * can replicate this behavior by providing their own conditional grant for
- * nid = 0. For example, hook_node_grants() can return the following array to
- * give the 'view' privilege to all nodes:
- * @code
- * if ($op == 'view') {
- *   $grants['example_realm'] = array(0);
- * }
- * @endcode
+ * provides this record if no node access modules are enabled.
  *
  * @return
  *   TRUE if 'view' access to all nodes is granted, FALSE otherwise.
-- 
1.7.3.1