Fix documentation of auth.gitBasicAuthPolicy and add Javadoc

Update the documentation to clarify:

- The HTTP password is not always randomly generated; it could have
  been set for example by the set-account ssh command.

- OAuth delegates authentication to the provider, which could use
  any way to authenticate the user, not only by password.

And also add the same documentation in the Javadoc for the
GitBasicAuthPolicy which is exposed in the extension API.

Change-Id: I61a2a53c509215865745e7a5686bb022fd36c3fe

Documentation/config-gerrit.txt

@@ -544,8 +544,7 @@ The supported values are:
 +
 *`HTTP`
 +
-Only the randomly generated HTTP password is accepted when doing Git over HTTP
-and REST API requests.
+Only the HTTP password is accepted when doing Git over HTTP and REST API requests.
 +
 *`LDAP`
 +
@@ -554,7 +553,7 @@ requests.
 +
 *`OAUTH`
 +
-Only the `OAUTH` password is allowed when doing Git over HTTP and REST API
+Only the `OAUTH` authentication is allowed when doing Git over HTTP and REST API
 requests.
 +
 *`HTTP_LDAP`

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/client/GitBasicAuthPolicy.java

@@ -15,8 +15,18 @@
 package com.google.gerrit.extensions.client;
 
 public enum GitBasicAuthPolicy {
+  /** Only the HTTP password is accepted when doing Git over HTTP and REST API requests. */
   HTTP,
+
+  /** Only the LDAP password is allowed when doing Git over HTTP and REST API requests. */
   LDAP,
+
+  /**
+   * The password in the request is first checked against the HTTP password and, if it does not
+   * match, it is then validated against the LDAP password.
+   */
   HTTP_LDAP,
+
+  /** Only the `OAUTH` authentication is allowed when doing Git over HTTP and REST API requests. */
   OAUTH
 }