diff --git includes/interfaces.inc includes/interfaces.inc
index 9db1436..0ff526e 100644
--- includes/interfaces.inc
+++ includes/interfaces.inc
@@ -148,7 +148,7 @@ interface VersioncontrolRepositoryGetItem {
    *        repository/path/revision combination is always unique, so no
    *        additional information is needed.
    *   - 'label': A label array with at least 'name' and 'type' elements
-   *        filled in. If a label is provided, it should be incorporated
+   *        filled in. If a label is specified, it should be incorporated
    *        into the result item as 'selected_label' (see return value
    *        docs), and will cause the most recent item on the label to
    *        be fetched. If the label includes an additional 'date'
@@ -207,18 +207,108 @@ interface VersioncontrolUserMapperInterface {
 
 interface VersioncontrolAuthHandlerInterface {
   public function setRepository(VersioncontrolRepository $repository);
+
   /**
-   * Determine whether this user has any access at all to the repository.
+   * Determine whether the specified user has any access at all to the
+   * repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
    *
-   * Implementing code should always check this first to get around having to
-   * do more complex checks.
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
    */
   public function authAccess($uid);
+
+  /**
+   * Determine whether the specified user has access to create new branches in
+   * the repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   *
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   public function authBranchCreate($uid);
+
+  /**
+   * Determine whether the specified user has access to delete the specified
+   * branch in the repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @param VersioncontrolBranch $branch
+   *   The VersioncontrolBranch object representing the branch against which
+   *   authorization checks should be made.
+   *
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   public function authBranchDelete($uid, VersioncontrolBranch $branch);
+
+  /**
+   * Determine whether the specified user has access to write to the specified
+   * branch in the repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @param VersioncontrolBranch $branch
+   *   The VersioncontrolBranch object representing the branch against which
+   *   authorization checks should be made.
+   *
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   public function authBranchUpdate($uid, VersioncontrolBranch $branch);
+
+  /**
+   * Determine whether the specified user has access to create new tags in the
+   * repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   public function authTagCreate($uid);
+
+  /**
+   * Determine whether the specified user has access to delete the specified
+   * tag in the repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @param VersioncontrolTag $tag
+   *   The VersioncontrolTag object representing the tag against which
+   *   authorization checks should be made.
+   *
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   public function authTagDelete($uid, VersioncontrolTag $tag);
+
+  /**
+   * Determine whether the specified user has access to update or modify
+   * the specified tag in the repository.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @param VersioncontrolTag $tag
+   *   The VersioncontrolTag object representing the tag against which
+   *   authorization checks should be made.
+   *
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   public function authTagUpdate($uid, VersioncontrolTag $tag);
+
+  /**
+   * Retrieve any errors messages that have been enqueued during auth checking.
+   *
+   * Most of the authorization methods will enqueue messages to indicate the
+   * reason for rejecting access. These messages may be useful for logging, or
+   * to provide as feedback to the user.
+   */
   public function getErrorMessages();
-}
\ No newline at end of file
+}
diff --git includes/plugins/vcs_auth/VersioncontrolAuthHandlerMappedAccounts.class.php includes/plugins/vcs_auth/VersioncontrolAuthHandlerMappedAccounts.class.php
index 658763e..132af84 100644
--- includes/plugins/vcs_auth/VersioncontrolAuthHandlerMappedAccounts.class.php
+++ includes/plugins/vcs_auth/VersioncontrolAuthHandlerMappedAccounts.class.php
@@ -1,5 +1,76 @@
 <?php
 
+/**
+ * A Versioncontrol authorization plugin which builds on a per-repository
+ * "account" model.
+ *
+ * This plugin builds an association between a VersioncontrolRepository and
+ * individual Drupal user accounts. It allows for highly granular per-branch and
+ * per-tag controls, but also provides easy higher-level permissions. There is
+ * no UI, but CRUD is provided, so you should be able to build UIs on top of
+ * this plugin, then use its CRUD features to store the data.
+ *
+ * The plugin maintains a per-user list of repository permissions. These
+ * permissions are all stored as an associative array, keyed on the uid to which
+ * they belong, in the $userData property. They are as follows:
+ *  - 'access': the outermost permission, indicating general access to the
+ *    repository.
+ *  - 'branch_create': permission indicating whether the user has access to
+ *    create branches.
+ *  - 'tag_create': permission indicating whether the user has access to create
+ *    tags.
+ *  - 'branch_update': permission indicating whether the user has access to
+ *    update/write to branches.
+ *  - 'tag_update': permission indicating whether the user has access to update
+ *    or write to tags.
+ *  - 'branch_update': permission indicating whether the user has access to
+ *    update/write to branches.
+ *  - 'tag_update': permission indicating whether the user has access to update
+ *    or write to tags.
+ *  - 'branch_delete': permission indicating whether the user has access to
+ *    delete branches.
+ *  - 'tag_delete': permission indicating whether the user has access to delete
+ *    tags.
+ *
+ * The system also maintains distinct update & delete permissions on a per-label
+ * (branch or tag) basis. For the most part, the above list of permissions are
+ * directly recorded in the $userData array using a simple boolean to indicate
+ * grant or deny (represented by VersioncontrolAuthHandlerMappedAccounts::DENY
+ * and VersioncontrolAuthHandlerMappedAccounts::GRANT). However, to allow for
+ * simpler UIs and decrease data synchronization overhead, the plugin uses a
+ * cascading auth logic that involves a third possible permission value,
+ * VersioncontrolAuthHandlerMappedAccounts::ALL, to be set on some of the above
+ * permissions. Here is the effect, in each case:
+ *
+ *  - 'access': if set to the ALL permission, this grants global authorization
+ *    to all operations on the repository, superceding any other DENYs.
+ *  - 'branch_update': if set to the ALL permission, authorization to
+ *    write to all branches is granted, superceding any any per-branch DENYs.
+ *  - 'branch_delete': same principle as 'branch_update', but for branch
+ *    deletion: supercedes any per-branch DENYs.
+ *  - 'tag_update': same principle as 'branch_update', but for tags.
+ *  - 'tag_delete': same principle as 'branch_delete', but for tags.
+ *
+ * This cascading logical flow can be represented hierarchically, where a parent
+ * is capable of superceding its children and producing a definitive auth
+ * response:
+ *
+ *    - 'access'
+ *      - 'branch_create'
+ *      - 'branch_update'
+ *        - (some branch foo) 'update'
+ *        - (some branch bar) 'update'
+ *      - 'branch_delete'
+ *        - (some branch foo) 'delete'
+ *        - (some branch bar) 'delete'
+ *      - 'tag_create'
+ *      - 'tag_update'
+ *        - (some tag foo) 'update'
+ *        - (some tag bar) 'update'
+ *      - 'tag_delete'
+ *        - (some tag foo) 'delete'
+ *        - (some tag bar) 'delete'
+ */
 class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandlerInterface {
   /**
    * The repository this plugin is working with.
@@ -9,16 +80,19 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
   protected $repository;
 
   /**
-   * The Drupal user this plugin is working with.
+   * Array containing all the user permissions data for the attached repository.
+   *
+   * @var array
    */
-  protected $user;
-
   protected $userData = array();
 
+  /**
+   * Boolean indicating whether the object has already run its build routine.
+   *
+   * @var bool
+   */
   protected $built = FALSE;
 
-  protected $userMasks = array();
-
   /**
    * An array of error message strings, to be formatted by sprintf when
    * VersioncontrolAuthHandlerMappedAccounts::getErrorMessages is called.
@@ -27,8 +101,21 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
    */
   protected $errors = array();
 
+  /**
+   * Permission value indicating access should be denied.
+   */
   const DENY  = 0;
+
+  /**
+   * Permission value indicating access should be granted.
+   *
+   */
   const GRANT = 1;
+
+  /**
+   * Permission value indicating access should be granted for this perm, AND
+   * for all child perms.
+   */
   const ALL   = 2;
 
   public function setRepository(VersioncontrolRepository $repository) {
@@ -56,7 +143,7 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
       ->fetchAllAssoc('uid', PDO::FETCH_ASSOC);
 
     foreach ($this->userData as &$data) {
-      $data['per-label-auth'] = array();
+      $data['per-label'] = array();
     }
 
     // Retrieve the extended per-label auth data
@@ -67,10 +154,10 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
 
     foreach ($label_data as $row) {
       $labeldata = array(
-        'update' => $row->update,
-        'delete' => $row->delete,
+        'label_update' => $row->label_update,
+        'label_delete' => $row->label_delete,
       );
-      $this->userData[$row->uid]['per-label-auth'][$row->label_id] = $labeldata;
+      $this->userData[$row->uid]['per-label'][$row->label_id] = $labeldata;
     }
 
     $this->built = TRUE;
@@ -86,6 +173,15 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
     return TRUE;
   }
 
+  /**
+   * Helper method - determine the base level of access to the repository for
+   * the specified user.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @return int
+   *   The base access level for the specified user, or 0 if not found.
+   */
   protected function baseAuth($uid) {
     $this->build();
     if (empty($this->userData[$uid])) {
@@ -138,6 +234,24 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
     return $this->authLabel($uid, $tag, 'update');
   }
 
+  /**
+   * Perform an authorization check on a specified user against a specified
+   * label for a specified op.
+   *
+   * This is just a shared helper method for the branch/tag update/delete
+   * methods, as they all have virtually identical logical flow.
+   *
+   * @param int $uid
+   *   The uid of the Drupal user to be checked.
+   * @param VersioncontrolEntity $label
+   *   Either a VersioncontrolTag or VersioncontrolBranch object, representing
+   *   the label against which authorization checks should be made.
+   * @param string $op
+   *   Either 'update' or 'delete'.
+   *
+   * @return bool
+   *   Boolean indicating access approved (TRUE) or denied (FALSE)
+   */
   protected function authLabel($uid, VersioncontrolEntity $label, $op) {
     $base = $this->baseAuth($uid);
     switch ($base) {
@@ -161,13 +275,22 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
     }
 
     // If we get this far, then we're doing a label-specific perm check.
-    return $this->userData[$uid]['per-label-auth'][$label->label_id][$op] == self::GRANT;
+    return $this->userData[$uid]['per-label'][$label->label_id]['label_' . $op] == self::GRANT;
   }
 
   public function getErrorMessages() {
     return $this->errors;
   }
 
+  /**
+   * Set the permissons on this repository for the specified user.
+   *
+   * @param int $uid
+   *   The uid to which the permissions data should be assigned.
+   *
+   * @param array $data
+   *   The array of permissions data to be assigned.
+   */
   public function setUserData($uid, $data) {
     $this->userData[$uid] = $data;
   }
@@ -176,8 +299,10 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
    * Retrieve the data representing a particular user's permission set, or the
    * entire set of permissions that have been set up for this repository.
    *
-   * @param int $uid
-   *   The uid for which to
+   * @param mixed $uid
+   *   Permissions data will be retrieved for this uid. If not provided, all
+   *   permissions data is returned.
+   *
    * @return mixed
    *   An array of perm data for the requested user, or an array of such arrays
    *   keyed on uid. If an invalid user is requested, returns FALSE.
@@ -214,7 +339,7 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
       $data['uid'] = $uid;
       $data['repo_id'] = $this->repository->repo_id;
 
-      foreach ($data['per-label-auth'] as $label_id => $label_data) {
+      foreach ($data['per-label'] as $label_id => $label_data) {
         $label_data['uid'] = $uid;
         $label_data['repo_id'] = $this->repository->repo_id;
         $label_data['label_id'] = $label_id;
@@ -222,7 +347,7 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
         $per_label_values[] = $label_data;
       }
 
-      unset($data['per-label-auth']);
+      unset($data['per-label']);
       $base_values[] = $data;
     }
 
@@ -238,7 +363,7 @@ class VersioncontrolAuthHandlerMappedAccounts implements VersioncontrolAuthHandl
     }
     $insert->execute();
 
-    $fields = array('uid', 'repo_id', 'label_id', 'update', 'delete');
+    $fields = array('uid', 'repo_id', 'label_id', 'label_update', 'label_delete');
     $insert = db_insert('versioncontrol_auth_account_label')->fields($fields);
 
     foreach ($per_label_values as $record) {
diff --git tests/VersioncontrolAccountAuthPlugin.test tests/VersioncontrolAccountAuthPlugin.test
index 60026c9..dd4d842 100644
--- tests/VersioncontrolAccountAuthPlugin.test
+++ tests/VersioncontrolAccountAuthPlugin.test
@@ -69,38 +69,38 @@ class VersioncontrolAccountAuthPlugin extends VersioncontrolTestCase {
         'tag_create' => VersioncontrolAuthHandlerMappedAccounts::DENY,
         'tag_update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
         'tag_delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
-        'per-label-auth' => array(
+        'per-label' => array(
           $this->branches[$repo_id][0]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
           ),
           $this->branches[$repo_id][1]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
           ),
           $this->branches[$repo_id][2]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
           ),
           $this->branches[$repo_id][3]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
           ),
           $this->tags[$repo_id][0]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
           ),
           $this->tags[$repo_id][1]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
           ),
           $this->tags[$repo_id][2]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::GRANT,
           ),
           $this->tags[$repo_id][3]->label_id => array(
-            'update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
-            'delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_update' => VersioncontrolAuthHandlerMappedAccounts::DENY,
+            'label_delete' => VersioncontrolAuthHandlerMappedAccounts::DENY,
           ),
         ),
       );
@@ -168,15 +168,4 @@ class VersioncontrolAccountAuthPlugin extends VersioncontrolTestCase {
       $this->assertFalse($authplug->authTagDelete($super_user->uid, $this->tags[$repo->repo_id][3]), 'granular tag delete validate correctly');
     }
   }
-
-  public function testAuthLogic() {
-    foreach ($this->repos as $repo) {
-      $this->doAuthLogicTest($repo);
-    }
-  }
-
-  public function doAuthLogicTest(VersioncontrolRepository $repo) {
-    $authplug = $repo->getAuthHandler();
-  }
-
 }
diff --git versioncontrol.install versioncontrol.install
index 03def0c..7004831 100644
--- versioncontrol.install
+++ versioncontrol.install
@@ -490,14 +490,14 @@ function versioncontrol_schema() {
         'unsigned' => TRUE,
         'not null' => TRUE,
       ),
-      'update' => array(
+      'label_update' => array(
         'type' => 'int',
         'description' => 'Grant user access to update/modify this label.',
         'size' => 'tiny',
         'not null' => TRUE,
         'default' => 0,
       ),
-      'delete' => array(
+      'label_delete' => array(
         'type' => 'int',
         'description' => 'Grant user access to delete this label.',
         'size' => 'tiny',
@@ -1066,14 +1066,14 @@ function versioncontrol_update_6309() {
         'unsigned' => TRUE,
         'not null' => TRUE,
       ),
-      'update' => array(
+      'label_update' => array(
         'type' => 'int',
         'description' => 'Grant user access to update/modify this label.',
         'size' => 'tiny',
         'not null' => TRUE,
         'default' => 0,
       ),
-      'delete' => array(
+      'label_delete' => array(
         'type' => 'int',
         'description' => 'Grant user access to delete this label.',
         'size' => 'tiny',