More Readme Work.

Author: Morgul

README.md

@@ -42,19 +42,123 @@ In TrivialPermissions, a `permission` is a string that looks like the following:
 
 This allows us to specify permissions on a per object basis. If you want to specify the permissions on an object from 
 the database, simply use that id as the object in the permission: `3dqZ7/somePerm`. Alternatively, you may wish to use
-more generic object names, like, `'Accounting'`, or `'Posts'`, or something along those lines. TrivialPermissions does
-not care, so long as you specify an object descriptor and a permission descriptor.
+more generic object descriptors, like, `'Accounting'`, or `'Posts'`. TrivialPermissions does not care, so long as you 
+specify an object descriptor and a permission descriptor.
 
 #### Glob Matching
 
 TrivialPermissions has special support for `*`. It can be used as either an object descriptor, or a permission descriptor.
 It matches any permissions passed in. If you want a user or group to have all permissions for all objects, specify
-`'*/**'`.
+`'*/*'`.
 
 ### Groups
 
+Groups are small objects with a name and a list of permissions. TrivialPermissions requires you to define (or load) these
+groups before you attempt to use them. This is generally considered part of the initial setup for TrivialPermissions. While
+TrivialPermissions allows you to use your own objects for users, it requires you to pre-load your groups. Our assumption is
+that you will not have more than 50 or so groups, and even if you do, loading under 1000 shouldn't be difficult for your
+application.
+
+#### Defining a Group
+
+* `defineGroup({ name: '...', permissions: [...] })` - Returns the created group object.
+
+Defining an individual group is very simple:
+
+```javascript
+var tp = require('../dist/trivialperms');
+
+// Create an 'Admins' group
+var admGroup = tp.defineGroup({ name: 'Admins', permissions: ['*/*'] });
+```
+
+#### Loading Groups
+
+* `loadGroups(listOrFunc)` - Returns a promise that resolves once all data has been loaded.
+
+More usefully, you will want to load multiple groups at once. TrivialPermissions supports loading from either a list of groups, or a function that returns a promise that resolves to a list of groups. The loading function itself always returns a promise.
+
+(Note: You _will_ need to wait until after the loading promise resolves before attempting to use the permissions system.)
+
+```javascript
+var tp = require('../dist/trivialperms');
+
+// Load from a list
+var loading = tp.loadGroups([
+    {
+        name: "Administrators",
+        permissions: [
+            "*/*"
+        ]
+    },
+    {
+        name: "Authors",
+        permissions: [
+            "Posts/canView",
+            "Posts/canAdd",
+            "Posts/canEdit"
+        ]
+    },
+    {
+        name: "Users",
+        permissions: [
+            "Posts/canView"
+        ]
+    }
+]);
+
+loading.then(function()
+{
+	// Do work here!
+});
+
+// Load from a function
+var loading = tp.loadGroups(function()
+{
+	return Promise.resolve([
+	    {
+	        name: "Administrators",
+	        permissions: [
+	            "*/*"
+	        ]
+	    },
+	    {
+	        name: "Authors",
+	        permissions: [
+	            "Posts/canView",
+	            "Posts/canAdd",
+	            "Posts/canEdit"
+	        ]
+	    },
+	    {
+	        name: "Users",
+	        permissions: [
+	            "Posts/canView"
+	        ]
+	    }
+	]);
+});
+
+loading.then(function()
+{
+	// Do work here!
+});
+```
+
+This should make it very easy to integrate with a database library, for example.
+
+### Users
+
+TBD.
+
+#### Setting Mapping
+
+TBD.
+
+#### Checking Permissions
+
 TBD.
 
-### Checking Permissions
+### Checking Group membership
 
 TBD.