node_access_example_node_grants needs doc update

Issue Summary

API page: http://api.drupal.org/api/examples/node_access_example--node_access_exam...

This is very poor english and is difficult to make sense of:

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.

The use of semicolon in this sentence suggests "two realms" will be described immediately after the semicolon. However, what follows that semicolon is only a garbled description of one of the realms. This description is difficult to understand:

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

Then the second realm gets addressed in another difficult to read paragraph

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.

"though" shouldn't break the first sentence. (why does it?)
"That" should not start a sentence (run-on sentence)

How about this as a rewrite:

Tell the node access system what GIDs the user belongs to for each realm. In this example, we are putting the user in two realms.

The first realm is the "example" realm. This realm is identified by a single group id, 1. Depending on the operation ($op) and the access permission ( user_access() ), the user is designated as a member of the group by adding array(1) to the $grants['example'] array.

//TODO: explain why the array is array(1) -- is the 1 a reference to group id?
//TODO: explain, can the array that is getting set to $grants['example'] contain multiple group ids?

We are also setting up a realm to give the node author special privileges, the "example_author" realm. This realm has 1 GID for every UID. Each user becomes a member of the group where GID == UID by combination of this code and the code in node_access_example_node_access_records().