diff --git node_access_example/node_access_example.module node_access_example/node_access_example.module
index 86416a5..c49f3a9 100755
--- node_access_example/node_access_example.module
+++ node_access_example/node_access_example.module
@@ -3,72 +3,181 @@
 
 /**
  * @file
- * This is an example illustrating how to restrict access to nodes based on
- * some criterion associated with the user.
- *
- * This example module will simply set a single flag on a node: 'private'. If
- * the flag is set, only users with the 'view private content' flag can see
- * the node, and all users with 'edit private content' can edit (but not
- * delete) the node.
- *
- * Additionally we will ensure that the node author can always view, edit,
- * and delete the node by providing an additional access realm that grants
- * privileges to the node's author.
- *
- * Database definition:
- * @code
- *   CREATE TABLE node_access_example (
- *     nid int(10) unsigned NOT NULL default '0' PRIMARY KEY,
- *     private int,
- *     KEY `node_example_nid` (nid)
- *   )
- * @endcode
+ * Module file illustrating API-based node access.
  */
 
 /**
- * Implementation of hook_perm().
+ * @defgroup node_access_example Example: Node Access
+ * @ingroup examples
+ * @{
+ * Demonstrates node access.
  *
- * In this example, we will use a simple permission to determine whether a user
- * has access to "private" content. This permission is defined here.
+ * This is an example demonstrating how to grant or deny access to nodes
+ * using the Drupal 6 core API node access system.
+ *
+ * This module will add a 'private' flag for each node, which the node's
+ * author can manage. Nodes marked private can only be viewed, edited,
+ * or deleted by the author. However, not everything is as private as it
+ * seems on the internet, and so we need to implement some ways to allow
+ * other users to manage this 'private' content.
+ *
+ * We will use the node grant system to specify which users are allowed
+ * to view, edit, or delete 'private' content.
+ *
+ * We use NodeAPI hooks to put a single marker on a node, called
+ * 'private'. The marker is implemented by a database table which has one row
+ * per node simply indicating that the node is private. If the "private"
+ * marker is set, other users are denied access.
+ *
+ * Standard permissions are defined which allow users with
+ * 'access any private content' or 'edit any private content' to override
+ * the 'private' node access restrictions.
+ *
+ * A separate access realm grants privileges to each node's author, so that
+ * they can always view, edit, and delete their own private nodes.
+ *
+ * The only page provided by this module gives a rundown of how many nodes
+ * are marked private, and how many of those are accessible to the current
+ * user. This demonstrates the use of the 'node_access' tag in node queries,
+ * preventing disclosure of information which should not be shown to users
+ * who don't have the proper permissions.
+ *
+ * Most relevant functions:
+ * - node_access_example_perm()
+ * - node_access_example_node_access_records()
+ * - node_access_example_node_grants()
+ *
+ * Drupal's node access system has two layers.
+ * - Overall override permissions. User 1 and any user with 'bypass node access'
+ *   permission are automatically granted access.
+ * - If no resolution has yet been reached, then the node_access table is used
+ *   along with hook_node_grants(). (Drupal updates the node_access table when nodes
+ *   are saved, by calling hook_node_access_records().)
+ *
+ * Note that the hook_node_grants()/hook_node_access_records() layer is a
+ * first-grant-wins system, which means a module using it can't deny access to a
+ * node. Contributed modules have been developed to overcome this shortcoming,
+ * with their own APIs, such as @link http://drupal.org/project/acl ACL. @endlink
+ * ACL, in fact, has emerged as the more-or-less standard solution for fine-grained
+ * access control, and you really should be reading up on it. Many modules use it,
+ * and if your module implements another node access system, there could be chaos.
+ *
+ * A list of the many node access modules (and differing APIs) is here:
+ * @link http://drupal.org/node/270000 Overview of Node Access Modules. @endlink
+ *
+ * @see node_access()
+ * @see hook_node_grants()
+ * @see hook_node_access_records()
+ */
+
+/**
+ * Implements hook_permission().
+ *
+ * We create two permissions, which we can use as a base for our grant/deny decision:
+ *
+ * - 'access any private content' allows global access to content marked
+ *   private by other users.
+ * - 'edit any private content' allows global edit
+ *   privileges, basically overriding the node access system.
  */
 function node_access_example_perm() {
-  return array('access private content', 'edit private content');
+  return array('access any private content', 'edit any private content');
 }
 
 /**
- * Implementation of hook_node_grants().
+ * Here we define a constant for our node access grant ID, for the 
+ * node_access_example_view and node_access_example_edit realms. This ID could
+ * be any integer, but here we choose 23, because it is this author's favorite
+ * number.
+ */
+define('NODE_ACCESS_EXAMPLE_GRANT_ALL', 23);
+
+/**
+ * Implements hook_node_grants().
+ *
+ * Tell the node access system what grant IDs the user belongs to for each realm,
+ * based on the operation being performed.
  *
- * Tell the node access system what GIDs the user belongs to for each realm.
- * In this example, we are providing two realms: the example realm, which
- * has just one group id (1) and the user is either a member or not depending
- * upon the operation and the access permission set.
+ * When the user tries to perform an operation on the node, Drupal calls
+ * hook_node_grants() to determine grant ID and realm for the user. Drupal
+ * looks up the grant ID and realm for the node, and compares them to the
+ * grant ID and realm provided here. If grant ID and realm match for both
+ * user and node, then the operation is allowed.
  *
- * We are also setting up a realm for the node author, though, to give it
- * special privileges. That has 1 GID for every UID, and each user is
- * automatically a member of the group where GID == UID.
+ * Grant ID and realm are both determined per node, by your module in
+ * hook_node_access_records().
  *
+ * In our example, we've created three access realms: One for authorship, and
+ * two that track with the permission system.
+ *
+ * We always add node_access_example_author to the list of grants, with a grant
+ * ID equal to their user ID. We do this because in our model, authorship always
+ * gives you permission to edit or delete your nodes, even if they're marked
+ * private.
+ *
+ * Then we compare the user's permissions to the operation to determine whether the
+ * user falls into the other two realms: node_access_example_view, and/or
+ * node_access_example_edit. If the user has the 'access any private content' 
+ * permission we defined in hook_permission(), they're declared as belonging to
+ * the node_access_example_realm. Similarly, if they have the 'edit any private
+ * content' permission, we add the node_access_example_edit realm to the list of
+ * grants they have.
+ *
+ * @see node_access_example_permission()
+ * @see node_access_example_node_access_records()
  */
 function node_access_example_node_grants($account, $op) {
-  if ($op == 'view' && user_access('access private content', $account)) {
-    $grants['example'] = array(1);
+  // 'access private content' and 'edit private content' are permissions we
+  // defined in hook_perm().
+  if ($op == 'view' && user_access('access any private content', $account)) {
+    $grants['node_access_example_private_realm'] = array(1);
   }
 
-  if (($op == 'update' || $op == 'delete') && user_access('edit private content', $account)) {
-    $grants['example'] = array(1);
+  if (($op == 'update' || $op == 'delete') && user_access('edit any private content', $account)) {
+    $grants['node_access_example_private_realm'] = array(1);
   }
 
-  $grants['example_author'] = array($account->uid);
+  // And finally everyone gets their own GID within node_access_example_author_realm.
+  $grants['node_access_example_author_realm'] = array($account->uid);
   return $grants;
 }
 
 /**
- * Implementation of hook_node_access_records().
+ * Implements hook_node_access_records().
  *
  * All node access modules must implement this hook. If the module is
  * interested in the privacy of the node passed in, return a list
- * of node access values for each grant ID we offer. Since this
- * example module only offers 1 grant ID, we will only ever be
- * returning one record.
+ * of node access values for each grant ID we offer.
+ *
+ * In this example, for each node which is marked 'private,' we define
+ * three realms:
+ * 
+ * The first and second are realms are 'node_access_example_view' and
+ * 'node_access_example_edit,' which have a single grant ID, 1. The
+ * user is either a member of these realms or not, depending upon the
+ * operation and the access permission set.
+ *
+ * The third is node_access_example_author. It gives the node
+ * author special privileges. node_access_example_author has one grant ID for
+ * every UID, and each user is automatically a member of the group where
+ * GID == UID. This has the effect of giving each user their own grant ID
+ * for nodes they authored, within this realm.
+ * 
+ * Drupal calls this hook when a node is saved, or when access permissions
+ * change in order to rebuild the node access database table(s).
+ *
+ * The array you return will define the realm and the grant ID for the
+ * given node. This is stored in the {node_access} table for subsequent
+ * comparison against the user's realm and grant IDs, which you'll
+ * supply in hook_node_grants().
+ *
+ * Realm names and grant IDs are arbitrary. Official drupal naming
+ * conventions do not cover access realms, but since all realms are
+ * stored in the same database table, it's probably a good idea to
+ * use descriptive names which follow the module name, such as
+ * 'mymodule_realmname'.
+ *
+ * @see node_access_example_node_grants()
  */
 function node_access_example_node_access_records($node) {
   // We only care about the node if it's been marked private. If not, it is
@@ -76,7 +185,7 @@ function node_access_example_node_access_records($node) {
   if (!empty($node->private)) {
     $grants = array();
     $grants[] = array(
-      'realm' => 'example',
+      'realm' => 'node_access_example_private_realm',
       'gid' => TRUE,
       'grant_view' => TRUE,
       'grant_update' => FALSE,
@@ -87,7 +196,7 @@ function node_access_example_node_access_records($node) {
     // For the example_author array, the GID is equivalent to a UID, which
     // means there are many many groups of just 1 user.
     $grants[] = array(
-      'realm' => 'example_author',
+      'realm' => 'node_access_example_author_realm',
       'gid' => $node->uid,
       'grant_view' => TRUE,
       'grant_update' => TRUE,
@@ -96,6 +205,7 @@ function node_access_example_node_access_records($node) {
     );
     return $grants;
   }
+  // Return nothing if the node has not been marked private.
 }
 
 /**
@@ -104,6 +214,7 @@ function node_access_example_node_access_records($node) {
  * This module adds a simple checkbox to the node form labeled private. If the
  * checkbox is labelled, only the node author and users with 'access private content'
  * privileges may see it.
+ *
  */
 function node_access_example_form_alter(&$form, $form_state) {
   if ($form['#id'] == 'node-form') {
@@ -119,7 +230,10 @@ function node_access_example_form_alter(&$form, $form_state) {
 /**
  * Implementation of hook_nodeapi().
  *
- * The module must track the access status of the node.
+ * The module must track the privacy status of the node.
+ *
+ * @see nodeapi_example.module
+ *
  */
 function node_access_example_nodeapi(&$node, $op, $arg = 0) {
   switch ($op) {