Issue #1227396 by chris.leversuch, jhodgdon: Document that hook_node_access() is not called on node listings.

modules/node/node.api.php

@@ -570,6 +570,10 @@ function hook_node_load($nodes, $types) {
  * block access, return NODE_ACCESS_IGNORE or simply return nothing.
  * Blindly returning FALSE will break other node access modules.
  *
+ * Also note that this function isn't called for node listings (e.g., RSS feeds,
+ * the default home page at path 'node', a recent content block, etc.) See
+ * @link node_access Node access rights @endlink for a full explanation.
+ *
  * @param $node
  *   Either a node object or the machine name of the content type on which to
  *   perform the access check.

modules/node/node.module

@@ -2790,13 +2790,14 @@ function node_search_validate($form, &$form_state) {
  * that this table is a list of grants; any matching row is sufficient to
  * grant access to the node.
  *
- * 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". This will allow modules dealing with node access to ensure
- * only nodes to which the user has access are retrieved, through the use of
- * hook_query_TAG_alter().
+ * In node listings (lists of nodes generated from a select query, such as the
+ * default home page at path 'node', an RSS feed, a recent content block, etc.),
+ * 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". This will allow
+ * modules dealing with node access to ensure only nodes to which the user has
+ * access are retrieved, through the use of hook_query_TAG_alter().
  *
  * 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