Index: modules/node/node.api.php
===================================================================
RCS file: /cvs/drupal/drupal/modules/node/node.api.php,v
retrieving revision 1.83
diff -u -r1.83 node.api.php
--- modules/node/node.api.php	3 Jan 2011 18:03:54 -0000	1.83
+++ modules/node/node.api.php	15 Jan 2011 21:09:57 -0000
@@ -131,7 +131,7 @@
  *
  * The realms and grant IDs can be arbitrarily defined by your node access
  * module; it is common to use role IDs as grant IDs, but that is not
- * required. Your module could instead maintain its own list of users, where
+ * required. Your module could instead maintain its own lists of users, where
  * each list has an ID. In that case, the return value of this hook would be
  * an array of the list IDs that this user is a member of.
  *
@@ -141,6 +141,11 @@
  * module's responsibility to provide appropriate realms to limit access to
  * unpublished content.
  *
+ * However, note that node access queries will not function well if you have a
+ * very large number of realms or grant IDs. See the
+ * @link node_access Node Access topic @endlink
+ * for more information.
+ *
  * Node access records are stored in the {node_access} table and define which
  * grants are required to access a node. There is a special case for the view
  * operation -- a record with node ID 0 corresponds to a "view all" grant for
Index: modules/node/node.module
===================================================================
RCS file: /cvs/drupal/drupal/modules/node/node.module,v
retrieving revision 1.1336
diff -u -r1.1336 node.module
--- modules/node/node.module	3 Jan 2011 18:03:54 -0000	1.1336
+++ modules/node/node.module	15 Jan 2011 21:09:57 -0000
@@ -2762,35 +2762,47 @@
  *
  * In determining access rights for a node, node_access() first checks
  * whether the user has the "bypass node access" permission. Such users have
- * unrestricted access to all nodes. user 1 will always pass this check.
+ * unrestricted access to all nodes. User 1 will always pass this check.
  *
  * Next, all implementations of hook_node_access() will be called. Each
  * implementation may explicitly allow, explicitly deny, or ignore the access
- * request. If at least one module says to deny the request, it will be rejected.
- * If no modules deny the request and at least one says to allow it, the request
- * will be permitted.
- *
- * If all modules ignore the access request, then the node_access table is used
- * to determine access. All node access modules are queried using
- * hook_node_grants() to assemble a list of "grant IDs" for the user. This list
- * is compared against the table. If any row contains the node ID in question
- * (or 0, which stands for "all nodes"), one of the grant IDs returned, and a
- * value of TRUE for the operation in question, then access is granted. Note
- * that this table is a list of grants; any matching row is sufficient to
- * grant access to the node.
+ * request. If at least one module says to deny the request, it will be
+ * rejected. If no modules deny the request and at least one says to allow it,
+ * the request will be permitted.
+ *
+ * If all modules ignore the access request, then the {node_access} table is
+ * used to determine access. All node access modules are queried using
+ * hook_node_grants() to assemble a list of "grant IDs" within "realms" for the
+ * user. This list is compared against the table. If any row contains all of:
+ * - The node ID in question (or 0, which stands for "all nodes")
+ * - One of the realms returned by hook_node_grants()
+ * - One of the grant IDs for this realm returned by hook_node_grants()
+ * - A value of TRUE for the operation in question
+ * then access is granted. Note that {node_access} is a list of grants; any
+ * matching row is sufficient to grant access to the node. These grants are
+ * previously assembled by calls to hook_node_access_records() when a node is
+ * first created or updated.
+ *
+ * Also note that this access check is quite resource-intensive if there are a
+ * lot of grant IDs or a lot of realms in your node access system, and it may
+ * even fail to execute (see the code in functions node_access() and
+ * node_query_node_access_alter() for details). So it is not advisable to use
+ * this system for access permissions if it would result in more than a few
+ * grant IDs and realms. Instead, use hook_node_access() and/or
+ * hook_query_TAG_alter() with the 'node_access' query tag.
  *
  * In node listings, the process above is followed except that
  * hook_node_access() is not called on each node for performance reasons and for
  * proper functioning of the pager system. When adding a node listing to your
  * module, be sure to use a dynamic query created by db_select() and add a tag
- * of "node_access" to ensure that only nodes to which the user has access
+ * of 'node_access' to ensure that only nodes to which the user has access
  * are retrieved.
  *
  * Note: Even a single module returning NODE_ACCESS_DENY from hook_node_access()
  * will block access to the node. Therefore, implementers should take care to
  * not deny access unless they really intend to. Unless a module wishes to
  * actively deny access it should return NODE_ACCESS_IGNORE (or simply return
- * nothing) to allow other modules or the node_access table to control access.
+ * nothing) to allow other modules or the {node_access} table to control access.
  *
  * To see how to write a node access module of your own, see
  * node_access_example.module.