Merge "Update documentation for ExternalIds cache-based methods"
diff --git a/java/com/google/gerrit/server/account/externalids/ExternalIds.java b/java/com/google/gerrit/server/account/externalids/ExternalIds.java
index a0c5155..0755a6d 100644
--- a/java/com/google/gerrit/server/account/externalids/ExternalIds.java
+++ b/java/com/google/gerrit/server/account/externalids/ExternalIds.java
@@ -31,7 +31,12 @@
   /** Returns the external IDs of the specified account. */
   ImmutableSet<ExternalId> byAccount(Account.Id accountId) throws IOException;
 
-  /** Returns the external IDs of the specified account that have the given scheme. */
+  /**
+   * Returns the external IDs of the specified account that have the given scheme.
+   *
+   * <p>Callers to this method should care about accuracy rather than latency. For better latency
+   * performance, call {@link ExternalIdCache#byAccount} directly.
+   */
   ImmutableSet<ExternalId> byAccount(Account.Id accountId, String scheme) throws IOException;
 
   /** Returns all external IDs by account. */
@@ -43,12 +48,8 @@
    * <p>Each email should belong to a single external ID only. This means if more than one external
    * ID is returned there is an inconsistency in the external IDs.
    *
-   * <p>The external IDs are retrieved from the external ID cache. Each access to the external ID
-   * cache requires reading the SHA1 of the refs/meta/external-ids branch. If external IDs for
-   * multiple emails are needed it is more efficient to use {@link #byEmails(String...)} as this
-   * method reads the SHA1 of the refs/meta/external-ids branch only once (and not once per email).
-   *
-   * @see #byEmails(String...)
+   * <p>Callers to this method should care about accuracy rather than latency. For better latency
+   * performance, call {@link ExternalIdCache#byEmail(String)} directly.
    */
   ImmutableSet<ExternalId> byEmail(String email) throws IOException;
 
@@ -58,11 +59,8 @@
    * <p>Each email should belong to a single external ID only. This means if more than one external
    * ID for an email is returned there is an inconsistency in the external IDs.
    *
-   * <p>The external IDs are retrieved from the external ID cache. Each access to the external ID
-   * cache requires reading the SHA1 of the refs/meta/external-ids branch. If external IDs for
-   * multiple emails are needed it is more efficient to use this method instead of {@link
-   * #byEmail(String)} as this method reads the SHA1 of the refs/meta/external-ids branch only once
-   * (and not once per email).
+   * <p>Callers to this method should care about accuracy rather than latency. For better latency
+   * performance, call {@link ExternalIdCache#byEmails(String...)} directly.
    *
    * @see #byEmail(String)
    */
diff --git a/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdCacheImpl.java b/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdCacheImpl.java
index d7ff85c..dbfe205 100644
--- a/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdCacheImpl.java
+++ b/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdCacheImpl.java
@@ -70,6 +70,14 @@
     return get().byAccount();
   }
 
+  /**
+   * Each access to the external ID cache requires reading the SHA1 of the refs/meta/external-ids
+   * branch. If external IDs for multiple emails are needed it is more efficient to use {@link
+   * #byEmails(String...)} as this method reads the SHA1 of the refs/meta/external-ids branch only
+   * once (and not once per email).
+   *
+   * @see #byEmails(String...)
+   */
   @Override
   public ImmutableSetMultimap<String, ExternalId> byEmails(String... emails) throws IOException {
     AllExternalIds allExternalIds = get();
diff --git a/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdsNoteDbImpl.java b/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdsNoteDbImpl.java
index b09099d..7a2945c 100644
--- a/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdsNoteDbImpl.java
+++ b/java/com/google/gerrit/server/account/externalids/storage/notedb/ExternalIdsNoteDbImpl.java
@@ -59,7 +59,8 @@
       this.externalIdCache = null;
     } else {
       throw new IllegalStateException(
-          "The cache provided in ExternalIdsNoteDbImpl should be either ExternalIdCacheImpl or DisabledExternalIdCache");
+          "The cache provided in ExternalIdsNoteDbImpl should be either ExternalIdCacheImpl or"
+              + " DisabledExternalIdCache");
     }
     this.externalIdKeyFactory = externalIdKeyFactory;
     this.authConfig = authConfig;
@@ -111,11 +112,32 @@
     return externalIdCache.allByAccount();
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>The external IDs are retrieved from the external ID cache. Each access to the external ID *
+   * cache requires reading the SHA1 of the refs/meta/external-ids branch. If external IDs for *
+   * multiple emails are needed it is more efficient to use {@link #byEmails(String...)} as this *
+   * method reads the SHA1 of the refs/meta/external-ids branch only once (and not once per email).
+   *
+   * @see #byEmails(String...)
+   */
   @Override
   public ImmutableSet<ExternalId> byEmail(String email) throws IOException {
     return externalIdCache.byEmail(email);
   }
 
+  /**
+   * {@inheritDoc}
+   *
+   * <p>The external IDs are retrieved from the external ID cache. Each access to the external ID
+   * cache requires reading the SHA1 of the refs/meta/external-ids branch. If external IDs for
+   * multiple emails are needed it is more efficient to use this method instead of {@link
+   * #byEmail(String)} as this method reads the SHA1 of the refs/meta/external-ids branch only once
+   * (and not once per email).
+   *
+   * @see #byEmail(String)
+   */
   @Override
   public ImmutableSetMultimap<String, ExternalId> byEmails(String... emails) throws IOException {
     return externalIdCache.byEmails(emails);