Document the various AccountGroup.Type states better

There was some confusion on the repo-discuss list about what SYSTEM
vs. INTERNAL meant for an AccountGroup.  The names are certainly
less than obvious, so a bit more text describing how they differ
is worthwhile.

Change-Id: I13f2a50e3707f255994e7e06c9ddfeed4c3db998
Signed-off-by: Shawn O. Pearce <sop@google.com>

1 files changed, 28 insertions, 3 deletions

diff --git a/src/main/java/com/google/gerrit/client/reviewdb/AccountGroup.java b/src/main/java/com/google/gerrit/client/reviewdb/AccountGroup.java
index 79a35a5dfa..ad3825b3b6 100644
--- a/src/main/java/com/google/gerrit/client/reviewdb/AccountGroup.java
+++ b/src/main/java/com/google/gerrit/client/reviewdb/AccountGroup.java
@@ -105,13 +105,38 @@ public final class AccountGroup {
   }
 
   public static enum Type {
-    /** System defined and managed group, e.g. anonymous users. */
+    /**
+     * System defined and managed group, e.g. anonymous users.
+     * <p>
+     * These groups must be explicitly named by {@link SystemConfig} and are
+     * specially handled throughout the code. In UI contexts their membership is
+     * not displayed. When computing effective group membership for any given
+     * user account, these groups are automatically handled using specialized
+     * branch conditions.
+     */
     SYSTEM,
 
-    /** Group defined within our database. */
+    /**
+     * Group defined within our database.
+     * <p>
+     * An internal group has its membership fully enumerated in the database.
+     * The membership can be viewed and edited through the web UI by any user
+     * who is a member of the owner group. These groups are not treated special
+     * in the code.
+     */
     INTERNAL,
 
-    /** Group defined by external LDAP database. */
+    /**
+     * Group defined by external LDAP database.
+     * <p>
+     * A group whose membership is determined by the LDAP directory that we
+     * connect to for user and group information. In UI contexts the membership
+     * of the group is not displayed, as it may be exceedingly large, or might
+     * contain users who have never logged into this server before (and thus
+     * have no matching account record). Adding or removing users from an LDAP
+     * group requires making edits through the LDAP directory, and cannot be
+     * done through our UI.
+     */
     LDAP;
   }