diff --git a/README.md b/README.md
index e1da49c..582bd2c 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,16 @@
 
 Global ref-database interface for use with Gerrit Code Review.
 
-Enables the de-coupling between Gerrit, the multi-site plugin and the different
+Enables the de-coupling between Gerrit, its libModules and the different
 implementations of a globally shared ref-database.
 
 ## Design
 
-The design for a global ref-db interface for Gerrit has been
-[posted to the Gerrit Code Review project](https://gerrit-review.googlesource.com/c/homepage/+/237980)
-for review.
+[The design for a global ref-db interface](https://gerrit.googlesource.com/plugins/multi-site/+/refs/heads/master/DESIGN.md#global-ref_db-plugin)
+can be found as part of the multi-site design documentation, where it first
+originated and was approved by the community.
+
+## Bindings
+
+In order to consume this library, some Guice bindings need to be registered
+appropriately. More information in the relevant [documentation](./bindings.md).
\ No newline at end of file
diff --git a/bindings.md b/bindings.md
new file mode 100644
index 0000000..920b911
--- /dev/null
+++ b/bindings.md
@@ -0,0 +1,70 @@
+
+Bindings
+=========================
+
+This library expects consumers to register Guice bindings.
+Some sensible implementations are already been provided and they must be bound
+by the Gerrit libModule in order to work.
+
+Alternatively libModules can decide to provide their own implementations (or
+override existing ones) and bound those instead.
+
+This is an example of binding that would allow consuming libModules getting up and
+running with this library:
+
+```java
+public class FooModule extends FactoryModule {
+
+  private final Configuration cfg;
+
+  public FooModule(Configuration cfg) {
+    this.cfg = cfg;
+  }
+
+  @Override
+  protected void configure() {
+    bind(SharedRefDatabaseWrapper.class).in(Scopes.SINGLETON);
+    bind(SharedRefLogger.class).to(Log4jSharedRefLogger.class);
+    factory(LockWrapper.Factory.class);
+    factory(SharedRefDbRepository.Factory.class);
+    factory(SharedRefDbRefDatabase.Factory.class);
+    factory(SharedRefDbRefUpdate.Factory.class);
+    factory(SharedRefDbBatchRefUpdate.Factory.class);
+    factory(RefUpdateValidator.Factory.class);
+    factory(BatchRefUpdateValidator.Factory.class);
+    bind(SharedRefDbConfiguration.class).toInstance(cfg.getSharedRefDbConfiguration());
+    bind(GitRepositoryManager.class).to(SharedRefDbGitRepositoryManager.class);
+    if (cfg.getSharedRefDbConfiguration().getSharedRefDb().getEnforcementRules().isEmpty()) {
+      bind(SharedRefEnforcement.class).to(DefaultSharedRefEnforcement.class).in(Scopes.SINGLETON);
+    } else {
+      bind(SharedRefEnforcement.class)
+          .to(CustomSharedRefEnforcementByProject.class)
+          .in(Scopes.SINGLETON);
+    }
+  }
+}
+```
+
+## Ignored Refs - Optional
+
+Consumers of this library can specify an optional set of refs that should not
+be validated against the shared ref-db, this list should be provided via Guice
+named binding, for example:
+
+```java
+
+public class FooModule extends AbstractModule {
+
+@Override
+  protected void configure() {
+    // other bindings ...
+    bind(new TypeLiteral<ImmutableSet<String>>() {})
+        .annotatedWith(Names.named(SharedRefDbGitRepositoryManager.IGNORED_REFS))
+        .toInstance(
+            ImmutableSet.of(
+                "refs/foo/bar",
+                "refs/foo/baz"));
+    // other bindings ...
+  }
+}
+```
\ No newline at end of file
diff --git a/config.md b/config.md
new file mode 100644
index 0000000..21064be
--- /dev/null
+++ b/config.md
@@ -0,0 +1,60 @@
+
+global-refdb Configuration
+=========================
+
+Configuration should be specified in the `$site_path/etc/<libModule>.config` file of
+the libModule consuming this library.
+
+## Configuration parameters
+
+```ref-database.enabled```
+:   Enable the use of a global refdb
+    Defaults: true
+
+```ref-database.enforcementRules.<policy>```
+:   Level of consistency enforcement across sites on a project:refs basis.
+    Supports two values for enforcing the policy on multiple projects or refs.
+    If the project or ref is omitted, apply the policy to all projects or all refs.
+
+    The <policy> can have one of the following values:
+
+    1. REQUIRED - Throw an exception if a git ref-update is processed against
+    a local ref not yet in sync with the global refdb.
+    The user transaction is cancelled.
+
+    2. IGNORED - Ignore any validation against the global refdb.
+
+    *Example:*
+    ```
+    [ref-database "enforcementRules"]
+       IGNORED = AProject:/refs/heads/feature
+    ```
+
+    Ignore the alignment with the global refdb for AProject on refs/heads/feature.
+
+    Defaults: No rules = All projects are REQUIRED to be consistent on all refs.
+
+```projects.pattern```
+:   Specifies which projects should be validated against the global refdb.
+    It can be provided more than once, and supports three formats: regular
+    expressions, wildcard matching, and single project matching. All three
+    formats match case-sensitive.
+
+    Values starting with a caret `^` are treated as regular
+    expressions. For the regular expressions details please follow
+    official [java documentation](https://docs.oracle.com/javase/tutorial/essential/regex/).
+
+    Please note that regular expressions could also be used
+    with inverse match.
+
+    Values that are not regular expressions and end in `*` are
+    treated as wildcard matches. Wildcards match projects whose
+    name agrees from the beginning until the trailing `*`. So
+    `foo/b*` would match the projects `foo/b`, `foo/bar`, and
+    `foo/baz`, but neither `foobar`, nor `bar/foo/baz`.
+
+    Values that are neither regular expressions nor wildcards are
+    treated as single project matches. So `foo/bar` matches only
+    the project `foo/bar`, but no other project.
+
+    By default, all projects are matched.
\ No newline at end of file
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDatabase.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDatabase.java
index d1b6d53..dbc52e8 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDatabase.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDatabase.java
@@ -65,6 +65,7 @@
    * @param refName to store the value for.
    * @param currValue current expected value in the DB.
    * @param newValue new value to store.
+   * @param <T> Type of the current and new value
    * @return true if the put was successful; false otherwise.
    * @throws GlobalRefDbSystemError the reference cannot be put due to a system error.
    */
@@ -84,8 +85,8 @@
   /**
    * Verify if the DB contains a value for the specific project and ref name
    *
-   * @param project
-   * @param refName
+   * @param project name of the project containing the ref
+   * @param refName the name of the ref to check existence for
    * @return true if the ref exists on the project
    */
   boolean exists(Project.NameKey project, String refName);
@@ -104,6 +105,7 @@
    * @param project project name
    * @param refName reference name
    * @param clazz wanted Class of the returned value
+   * @param <T> Type of the object associate to project and ref
    * @return {@link java.util.Optional} of the value
    * @throws GlobalRefDbSystemError value cannot be returned due to a system error.
    */
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbLockException.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbLockException.java
index 5bf44e5..fa757db 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbLockException.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbLockException.java
@@ -14,10 +14,21 @@
 
 package com.gerritforge.gerrit.globalrefdb;
 
-/** Unable to lock a project/ref resource. */
+/**
+ * {@code GlobalRefDbLockException} is an exception that can be thrown when interacting with the
+ * global-refdb to represent the inability to lock or acquire a resource.
+ */
 public class GlobalRefDbLockException extends RuntimeException {
   private static final long serialVersionUID = 1L;
 
+  /**
+   * Constructs a new {@code GlobalRefDbLockException} with the specified project, refName and
+   * cause.
+   *
+   * @param project the project containing refName
+   * @param refName the specific ref for which the locking failed
+   * @param cause the cause of the locking failure
+   */
   public GlobalRefDbLockException(String project, String refName, Exception cause) {
     super(String.format("Unable to lock ref %s on project %s", refName, project), cause);
   }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbSystemError.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbSystemError.java
index 50dacd9..c470bff 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbSystemError.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/GlobalRefDbSystemError.java
@@ -14,9 +14,19 @@
 
 package com.gerritforge.gerrit.globalrefdb;
 
+/**
+ * {@code GlobalRefDbSystemError} is an exception that can be thrown when interacting with the
+ * global-refdb to represent any error in performing operations such as creating or deleting a ref.
+ */
 public class GlobalRefDbSystemError extends RuntimeException {
   private static final long serialVersionUID = 1L;
 
+  /**
+   * Constructs a new {@code GlobalRefDbSystemError} with the specified detail message and cause.
+   *
+   * @param msg the detail message
+   * @param cause the cause
+   */
   public GlobalRefDbSystemError(String msg, Exception cause) {
     super(msg, cause);
   }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/BatchRefUpdateValidator.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/BatchRefUpdateValidator.java
index 6c258ae..71d6621 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/BatchRefUpdateValidator.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/BatchRefUpdateValidator.java
@@ -14,6 +14,8 @@
 
 package com.gerritforge.gerrit.globalrefdb.validation;
 
+import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.CustomSharedRefEnforcementByProject;
+import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.DefaultSharedRefEnforcement;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.OutOfSyncException;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.SharedRefEnforcement;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.SharedRefEnforcement.EnforcePolicy;
@@ -33,9 +35,11 @@
 import org.eclipse.jgit.lib.RefDatabase;
 import org.eclipse.jgit.transport.ReceiveCommand;
 
+/** Enables the detection of out-of-sync by validating batch ref updates against the global refdb */
 public class BatchRefUpdateValidator extends RefUpdateValidator {
   private static final FluentLogger logger = FluentLogger.forEnclosingClass();
 
+  /** {@code BatchRefUpdateValidator} Factory for Guice assisted injection. */
   public interface Factory {
     BatchRefUpdateValidator create(
         String projectName, RefDatabase refDb, ImmutableSet<String> ignoredRefs);
@@ -45,6 +49,23 @@
     void apply(BatchRefUpdate batchRefUpdate, NoParameterVoidFunction arg) throws IOException;
   }
 
+  /**
+   * Constructs a {@code BatchRefUpdateValidator} able to check the validity of batch ref-updates
+   * against global refdb before execution.
+   *
+   * @param sharedRefDb an instance of the global refdb to check for out-of-sync refs.
+   * @param validationMetrics to update validation results, such as split-brains.
+   * @param refEnforcement Specific ref enforcements for this project. Either a {@link
+   *     CustomSharedRefEnforcementByProject} when custom policies are provided via configuration *
+   *     file or a {@link DefaultSharedRefEnforcement} for defaults.
+   * @param lockWrapperFactory factory providing a {@link LockWrapper}
+   * @param projectsFilter filter to match whether the project being updated should be validated
+   *     against global refdb
+   * @param projectName the name of the project being updated.
+   * @param refDb for ref operations
+   * @param ignoredRefs A set of refs for which updates should not be checked against the shared
+   *     ref-db
+   */
   @Inject
   public BatchRefUpdateValidator(
       SharedRefDatabaseWrapper sharedRefDb,
@@ -66,6 +87,24 @@
         ignoredRefs);
   }
 
+  /**
+   * Checks whether the provided batchRefUpdate should be validated first against the global refdb.
+   * If not it just execute the provided batchRefUpdateFunction. Upon success the batchRefUpdate is
+   * returned, upon failure split brain metrics are incremented and a {@link IOException} is thrown.
+   *
+   * <p>Validation is performed when either of these condition is true:
+   *
+   * <ul>
+   *   <li>The project being updated is a global project ({@link
+   *       RefUpdateValidator#isGlobalProject(String)}
+   *   <li>The enforcement policy for the project being updated is {@link EnforcePolicy#IGNORED}
+   * </ul>
+   *
+   * @param batchRefUpdate batchRefUpdate object
+   * @param batchRefUpdateFunction batchRefUpdate function to execute upon validation
+   * @throws IOException batch update failed
+   */
+  @SuppressWarnings("JavadocReference")
   public void executeBatchUpdateWithValidation(
       BatchRefUpdate batchRefUpdate, NoParameterVoidFunction batchRefUpdateFunction)
       throws IOException {
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModule.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModule.java
index 49b20d8..b8edc90 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModule.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModule.java
@@ -22,6 +22,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/** Binds {@link GlobalRefDatabase} to the {@link NoopSharedRefDatabase} */
 public class LibModule extends LifecycleModule {
   private static final Logger log = LoggerFactory.getLogger(LibModule.class);
 
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModuleLogFile.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModuleLogFile.java
index 075bcc9..c2858b4 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModuleLogFile.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LibModuleLogFile.java
@@ -20,8 +20,18 @@
 import org.apache.log4j.LogManager;
 import org.apache.log4j.Logger;
 
+/** Abstract class to be extended by lib modules willing to create file loggers. */
 public abstract class LibModuleLogFile {
 
+  /**
+   * Constructs an instance of {@code LibModuleLogFile} which creates an asynchronous appender with
+   * the provided logName and layout
+   *
+   * @param systemLog - to create the log appender
+   * @param logName - the name of the log file
+   * @param layout - the layout for the log
+   * @see org.apache.log4j.PatternLayout
+   */
   public LibModuleLogFile(SystemLog systemLog, String logName, Layout layout) {
     AsyncAppender asyncAppender = systemLog.createAsyncAppender(logName, layout, true, true);
     Logger logger = LogManager.getLogger(logName);
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LockWrapper.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LockWrapper.java
index 18d75a3..a1312b0 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LockWrapper.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/LockWrapper.java
@@ -17,7 +17,9 @@
 import com.google.inject.Inject;
 import com.google.inject.assistedinject.Assisted;
 
+/** Wrapper around an {@link AutoCloseable} lock to allow logging of resource releasing. */
 public class LockWrapper implements AutoCloseable {
+  /** {@code LockWrapper} Factory for Guice assisted injection. */
   public interface Factory {
     LockWrapper create(
         @Assisted("project") String project,
@@ -30,6 +32,15 @@
   private final AutoCloseable lock;
   private final SharedRefLogger sharedRefLogger;
 
+  /**
+   * Constructs a {@code LockWrapper} object for a specific refName of a project, which wraps a held
+   * lock, so that its details can be logged upon closure.
+   *
+   * @param sharedRefLogger to log the releasing of the lock
+   * @param project the project the lock has been acquired for
+   * @param refName the refName the lock has been acquired for
+   * @param lock the acquired lock
+   */
   @Inject
   public LockWrapper(
       SharedRefLogger sharedRefLogger,
@@ -42,6 +53,11 @@
     this.refName = refName;
   }
 
+  /**
+   * Release the acquired lock and logs the lock release operation.
+   *
+   * @throws Exception if this resource cannot be closed
+   */
   @Override
   public void close() throws Exception {
     lock.close();
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/Log4jSharedRefLogger.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/Log4jSharedRefLogger.java
index 5653ee2..7547cb7 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/Log4jSharedRefLogger.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/Log4jSharedRefLogger.java
@@ -40,6 +40,11 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Implementation of SharedRefLogger for Log4j. Logs to 'sharedref_log' file
+ *
+ * @see <a href="https://logging.apache.org/log4j/2.x/javadoc.html">log4j</a>
+ */
 @Singleton
 public class Log4jSharedRefLogger extends LibModuleLogFile implements SharedRefLogger {
   private static final String LOG_NAME = "sharedref_log";
@@ -49,6 +54,14 @@
 
   private static final FluentLogger logger = FluentLogger.forEnclosingClass();
 
+  /**
+   * Constructs a {@code Log4jSharedRefLogger} instance with the provided systemLog used to create
+   * the Log4J apppender and the repository manager to hydrate ref information with extra
+   * information, such as committer, before logging.
+   *
+   * @param systemLog systemLog to create log appender
+   * @param gitRepositoryManager to hydrate log entries with commit data
+   */
   @Inject
   public Log4jSharedRefLogger(SystemLog systemLog, GitRepositoryManager gitRepositoryManager) {
     super(systemLog, LOG_NAME, new PatternLayout("[%d{ISO8601}] [%t] %-5p : %m%n"));
@@ -56,6 +69,15 @@
     sharedRefDBLog = LoggerFactory.getLogger(LOG_NAME);
   }
 
+  /**
+   * {@inheritDoc}.
+   *
+   * <p>Only logs commits and blob refs (throws {@link IncorrectObjectTypeException} for any other
+   * unexpected type). Additionally, it hydrates commits with information about the committer and
+   * commit message.
+   *
+   * <p>Logs Json serialization of {@link SharedRefLogEntry.UpdateRef}
+   */
   @Override
   public void logRefUpdate(String project, Ref currRef, ObjectId newRefValue) {
     if (!ObjectId.zeroId().equals(newRefValue)) {
@@ -99,6 +121,12 @@
     }
   }
 
+  /**
+   * {@inheritDoc}.
+   *
+   * <p>Logs Json serialization of {@link SharedRefLogEntry.UpdateRef} or a {@link
+   * SharedRefLogEntry.DeleteRef}, when 'newRefValue' is null
+   */
   @Override
   public <T> void logRefUpdate(String project, String refName, T currRef, T newRefValue) {
     if (newRefValue != null) {
@@ -112,16 +140,31 @@
     }
   }
 
+  /**
+   * {@inheritDoc}.
+   *
+   * <p>Logs Json serialization of {@link SharedRefLogEntry.DeleteProject}
+   */
   @Override
   public void logProjectDelete(String project) {
     sharedRefDBLog.info(gson.toJson(new SharedRefLogEntry.DeleteProject(project)));
   }
 
+  /**
+   * {@inheritDoc}.
+   *
+   * <p>Logs Json serialization of {@link SharedRefLogEntry.LockAcquire}
+   */
   @Override
   public void logLockAcquisition(String project, String refName) {
     sharedRefDBLog.info(gson.toJson(new SharedRefLogEntry.LockAcquire(project, refName)));
   }
 
+  /**
+   * {@inheritDoc}.
+   *
+   * <p>Logs Json serialization of {@link SharedRefLogEntry.LockRelease}
+   */
   @Override
   public void logLockRelease(String project, String refName) {
     sharedRefDBLog.info(gson.toJson(new SharedRefLogEntry.LockRelease(project, refName)));
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectDeletedSharedDbCleanup.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectDeletedSharedDbCleanup.java
index ec72bcc..5a0cad7 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectDeletedSharedDbCleanup.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectDeletedSharedDbCleanup.java
@@ -20,6 +20,7 @@
 import com.google.gerrit.extensions.events.ProjectDeletedListener;
 import com.google.inject.Inject;
 
+/** Removes a project from the global refdb upon deletion */
 public class ProjectDeletedSharedDbCleanup implements ProjectDeletedListener {
   private static final FluentLogger logger = FluentLogger.forEnclosingClass();
 
@@ -27,6 +28,13 @@
 
   private final ValidationMetrics validationMetrics;
 
+  /**
+   * Constructs a {@code ProjectDeletedSharedDbCleanup} with the provided validation metrics and
+   * shared ref-database
+   *
+   * @param sharedDb global refdb used to validate project deletion
+   * @param validationMetrics to increase split-brain upon project failed validation
+   */
   @Inject
   public ProjectDeletedSharedDbCleanup(
       SharedRefDatabaseWrapper sharedDb, ValidationMetrics validationMetrics) {
@@ -34,6 +42,13 @@
     this.validationMetrics = validationMetrics;
   }
 
+  /**
+   * Attempts to delete a project from the global refdb. Upon failure, it swallows {@link
+   * GlobalRefDbSystemError} exceptions and increments split brain metrics. Executed upon project
+   * deletion.
+   *
+   * @param event the project deletion event
+   */
   @Override
   public void onProjectDeleted(Event event) {
     String projectName = event.getProjectName();
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectsFilter.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectsFilter.java
index 3121df4..c215e34 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectsFilter.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ProjectsFilter.java
@@ -27,11 +27,35 @@
 
 // import com.google.gerrit.entities.AccessSection;
 
+/**
+ * Filter to match against project names to indicate whether a project should be validated against a
+ * global refdb.
+ *
+ * <p>Filters are computed by reading the configuration of the libModule consuming this library.
+ */
 @Singleton
 public class ProjectsFilter {
+
+  /** The type of the pattern defining this filter */
   public enum PatternType {
+    /**
+     * Values starting with a caret `^` are treated as regular expressions. For the regular
+     * expressions details please @see <a
+     * href="https://docs.oracle.com/javase/tutorial/essential/regex/">official java
+     * documentation</a>
+     */
     REGEX,
+    /**
+     * Values that are not regular expressions and end in `*` are treated as wildcard matches.
+     * Wildcards match projects whose name agrees from the beginning until the trailing `*`. So
+     * `foo/b*` would match the projects `foo/b`, `foo/bar`, and `foo/baz`, but neither `foobar`,
+     * nor `bar/foo/baz`.
+     */
     WILDCARD,
+    /**
+     * Values that are neither regular expressions nor wildcards are treated as single project
+     * matches. So `foo/bar` matches only the project `foo/bar`, but no other project.
+     */
     EXACT_MATCH;
 
     public static PatternType getPatternType(String pattern) {
@@ -51,11 +75,24 @@
   private Set<NameKey> localProjects = Sets.newConcurrentHashSet();
   private final List<String> projectPatterns;
 
+  /**
+   * Constructs a {@code ProjectsFilter} by providing the libModule configuration
+   *
+   * @param cfg the libModule configuration
+   */
   @Inject
   public ProjectsFilter(SharedRefDbConfiguration cfg) {
     projectPatterns = cfg.projects().getPatterns();
   }
 
+  /**
+   * Given an event checks whether this project filter matches the project associated with the
+   * event. Returns false for all other events.
+   *
+   * @see #matches(NameKey)
+   * @param event the event to check against
+   * @return true when it matches, false otherwise.
+   */
   public boolean matches(Event event) {
     if (event == null) {
       throw new IllegalArgumentException("Event object cannot be null");
@@ -66,10 +103,23 @@
     return false;
   }
 
+  /**
+   * checks whether this project filter matches the projectName
+   *
+   * @see #matches(NameKey)
+   * @param projectName the project name to check against
+   * @return true when it matches, false otherwise.
+   */
   public boolean matches(String projectName) {
     return matches(NameKey.parse(projectName));
   }
 
+  /**
+   * checks whether this project filter matches the project name.
+   *
+   * @param name the name of the project to check
+   * @return true, when the project matches, false otherwise.
+   */
   public boolean matches(Project.NameKey name) {
     if (name == null || Strings.isNullOrEmpty(name.get())) {
       throw new IllegalArgumentException(
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefPair.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefPair.java
index 7156a7e..4211c0c 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefPair.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefPair.java
@@ -17,11 +17,23 @@
 import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.Ref;
 
+/**
+ * A convenience object encompassing the old (current) and the new (candidate) value of a {@link
+ * Ref}. This is used to snapshot the current status of a ref update so that validations against the
+ * global refdb are unaffected by changes on the {@link org.eclipse.jgit.lib.RefDatabase}.
+ */
 public class RefPair {
   public final Ref compareRef;
   public final ObjectId putValue;
   public final Exception exception;
 
+  /**
+   * Constructs a {@code RefPair} with the provided old and new ref values. The oldRef value is
+   * required not to be null, in which case an {@link IllegalArgumentException} is thrown.
+   *
+   * @param oldRef the old ref
+   * @param newRefValue the new (candidate) value for this ref.
+   */
   RefPair(Ref oldRef, ObjectId newRefValue) {
     if (oldRef == null) {
       throw new IllegalArgumentException("Required not-null ref in RefPair");
@@ -31,16 +43,33 @@
     this.exception = null;
   }
 
+  /**
+   * Constructs a {@code RefPair} with the current ref and an Exception indicating why the new ref
+   * value failed being retrieved.
+   *
+   * @param newRef
+   * @param e
+   */
   RefPair(Ref newRef, Exception e) {
     this.compareRef = newRef;
     this.exception = e;
     this.putValue = ObjectId.zeroId();
   }
 
+  /**
+   * Getter for the current ref
+   *
+   * @return the current ref value
+   */
   public String getName() {
     return compareRef.getName();
   }
 
+  /**
+   * Whether the new value failed being retrieved
+   *
+   * @return true when this refPair has failed, false otherwise.
+   */
   public boolean hasFailed() {
     return exception != null;
   }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefUpdateValidator.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefUpdateValidator.java
index cf93e1d..16dee20 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefUpdateValidator.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/RefUpdateValidator.java
@@ -15,6 +15,8 @@
 package com.gerritforge.gerrit.globalrefdb.validation;
 
 import com.gerritforge.gerrit.globalrefdb.GlobalRefDbSystemError;
+import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.CustomSharedRefEnforcementByProject;
+import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.DefaultSharedRefEnforcement;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.OutOfSyncException;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.SharedDbSplitBrainException;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.SharedLockException;
@@ -34,6 +36,7 @@
 import org.eclipse.jgit.lib.RefDatabase;
 import org.eclipse.jgit.lib.RefUpdate;
 
+/** Enables the detection of out-of-sync by validating ref updates against the global refdb. */
 public class RefUpdateValidator {
   private static final FluentLogger logger = FluentLogger.forEnclosingClass();
 
@@ -47,6 +50,7 @@
   protected final ProjectsFilter projectsFilter;
   private final ImmutableSet<String> ignoredRefs;
 
+  /** {@code RefUpdateValidator} Factory for Guice assisted injection. */
   public interface Factory {
     RefUpdateValidator create(
         String projectName, RefDatabase refDb, ImmutableSet<String> ignoredRefs);
@@ -69,6 +73,23 @@
     void invoke() throws IOException;
   }
 
+  /**
+   * Constructs a {@code RefUpdateValidator} able to check the validity of ref-updates against a
+   * global refdb before execution.
+   *
+   * @param sharedRefDb an instance of the global refdb to check for out-of-sync refs.
+   * @param validationMetrics to update validation results, such as split-brains.
+   * @param refEnforcement Specific ref enforcements for this project. Either a {@link
+   *     CustomSharedRefEnforcementByProject} when custom policies are provided via configuration
+   *     file or a {@link DefaultSharedRefEnforcement} for defaults.
+   * @param lockWrapperFactory factory providing a {@link LockWrapper}
+   * @param projectsFilter filter to match whether the project being updated should be validated
+   *     against global refdb
+   * @param projectName the name of the project being updated.
+   * @param refDb for ref operations
+   * @param ignoredRefs A set of refs for which updates should not be checked against the shared
+   *     ref-db
+   */
   @Inject
   public RefUpdateValidator(
       SharedRefDatabaseWrapper sharedRefDb,
@@ -89,6 +110,30 @@
     this.projectsFilter = projectsFilter;
   }
 
+  /**
+   * Checks whether the provided refUpdate should be validated first against the shared ref-db. If
+   * not it just execute the provided refUpdateFunction. If it should be validated against the
+   * global refdb then it does so by executing the {@link
+   * RefUpdateValidator#doExecuteRefUpdate(RefUpdate, NoParameterFunction)} first. Upon success the
+   * refUpdate is returned, upon failure split brain metrics are incremented and a {@link
+   * SharedDbSplitBrainException} is thrown.
+   *
+   * <p>Validation is performed when either of these condition is true
+   *
+   * <ul>
+   *   <li>The ref being updated is not to be ignored ({@link
+   *       RefUpdateValidator#isRefToBeIgnored(String)})
+   *   <li>The project being updated is a global project ({@link
+   *       RefUpdateValidator#isGlobalProject(String)}
+   *   <li>The enforcement policy for the project being updated is {@link EnforcePolicy#IGNORED}
+   * </ul>
+   *
+   * @param refUpdate the refUpdate command
+   * @param refUpdateFunction the refUpdate function to execute after validation
+   * @return the result of the update, or "null" in case a split brain was detected but the policy
+   *     enforcement was not REQUIRED
+   * @throws IOException Execution of ref update failed
+   */
   public RefUpdate.Result executeRefUpdate(
       RefUpdate refUpdate, NoParameterFunction<RefUpdate.Result> refUpdateFunction)
       throws IOException {
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDatabaseWrapper.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDatabaseWrapper.java
index d9c8051..4b5aeec 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDatabaseWrapper.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDatabaseWrapper.java
@@ -26,6 +26,11 @@
 import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.Ref;
 
+/**
+ * Wraps an instance of {@link GlobalRefDatabase} provided as {@link DynamicItem} via a Guice
+ * binding. Such instance is bound optionally and, in case no explicit binding is registered a
+ * {@link NoopSharedRefDatabase} instance is wrapped instead.
+ */
 public class SharedRefDatabaseWrapper implements GlobalRefDatabase {
   private static final GlobalRefDatabase NOOP_REFDB = new NoopSharedRefDatabase();
 
@@ -34,6 +39,12 @@
 
   private final SharedRefLogger sharedRefLogger;
 
+  /**
+   * Constructs a {@code SharedRefDatabaseWrapper} wrapping an optional {@link GlobalRefDatabase},
+   * which might have been bound by consumers of this library.
+   *
+   * @param sharedRefLogger logger of shared ref-db operations.
+   */
   @Inject
   public SharedRefDatabaseWrapper(SharedRefLogger sharedRefLogger) {
     this.sharedRefLogger = sharedRefLogger;
@@ -51,6 +62,7 @@
     return sharedRefDb().isUpToDate(project, ref);
   }
 
+  /** {@inheritDoc}. The operation is logged upon success. */
   @Override
   public boolean compareAndPut(Project.NameKey project, Ref currRef, ObjectId newRefValue)
       throws GlobalRefDbSystemError {
@@ -61,6 +73,7 @@
     return succeeded;
   }
 
+  /** {@inheritDoc} the operation is logged upon success. */
   @Override
   public <T> boolean compareAndPut(Project.NameKey project, String refName, T currValue, T newValue)
       throws GlobalRefDbSystemError {
@@ -71,6 +84,7 @@
     return succeeded;
   }
 
+  /** {@inheritDoc}. The operation is logged. */
   @Override
   public AutoCloseable lockRef(Project.NameKey project, String refName)
       throws GlobalRefDbLockException {
@@ -84,6 +98,7 @@
     return sharedRefDb().exists(project, refName);
   }
 
+  /** {@inheritDoc}. The operation is logged. */
   @Override
   public void remove(Project.NameKey project) throws GlobalRefDbSystemError {
     sharedRefDb().remove(project);
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbBatchRefUpdate.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbBatchRefUpdate.java
index 8065fe8..d7c0c61 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbBatchRefUpdate.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbBatchRefUpdate.java
@@ -29,6 +29,10 @@
 import org.eclipse.jgit.transport.ReceiveCommand;
 import org.eclipse.jgit.util.time.ProposedTimestamp;
 
+/**
+ * Batch of reference updates to be applied to a repository prior having checked the validity of
+ * those operations against the global refdb.
+ */
 public class SharedRefDbBatchRefUpdate extends BatchRefUpdate {
 
   private final BatchRefUpdate batchRefUpdate;
@@ -37,11 +41,22 @@
   private final RefDatabase refDb;
   private final ImmutableSet<String> ignoredRefs;
 
+  /** {@code SharedRefDbBatchRefUpdate} Factory for Guice assisted injection. */
   public interface Factory {
     SharedRefDbBatchRefUpdate create(
         String project, RefDatabase refDb, ImmutableSet<String> ignoredRefs);
   }
 
+  /**
+   * Constructs an instance of {@code SharedRefDbBatchRefUpdate} able to validate ref updates via a
+   * {@link BatchRefUpdateValidator}. It is basically a thin wrapper around {@link BatchRefUpdate},
+   * where the validity of the update operation is checked first against the global refdb instance.
+   *
+   * @param batchRefValidatorFactory Factory to provide {@link BatchRefUpdateValidator}
+   * @param project the project this batch update is for
+   * @param refDb a ref-database instance to create the underlying {@link BatchRefUpdate}
+   * @param ignoredRefs a set of refs that should not be validated against the global refdb
+   */
   @Inject
   public SharedRefDbBatchRefUpdate(
       BatchRefUpdateValidator.Factory batchRefValidatorFactory,
@@ -166,6 +181,21 @@
     return batchRefUpdate.addProposedTimestamp(ts);
   }
 
+  /**
+   * Execute this batch update by delegating to the underlying {@link BatchRefUpdate} after checking
+   * first the validity of the operation via a {@link BatchRefUpdateValidator}.
+   *
+   * @param walk a RevWalk to parse tags in case the storage system wants to store them pre-peeled,
+   *     a common performance optimization.
+   * @param monitor progress monitor to receive update status on.
+   * @param options a list of option strings; set null to execute without
+   * @throws IOException the database is unable to accept the update. This could be either caused by
+   *     one of the underlying update command or by the batch ref validator proving that the current
+   *     ref-db is not up-to-date with the global refdb
+   * @see BatchRefUpdate
+   * @see BatchRefUpdateValidator#executeBatchUpdateWithValidation(BatchRefUpdate,
+   *     RefUpdateValidator.NoParameterVoidFunction)
+   */
   @Override
   public void execute(RevWalk walk, ProgressMonitor monitor, List<String> options)
       throws IOException {
@@ -175,6 +205,20 @@
             batchRefUpdate, () -> batchRefUpdate.execute(walk, monitor, options));
   }
 
+  /**
+   * Execute this batch update by delegating to the underlying {@link BatchRefUpdate} after checking
+   * first the validity of the operation via a {@link BatchRefUpdateValidator}.
+   *
+   * @param walk a RevWalk to parse tags in case the storage system wants to store them pre-peeled,
+   *     a common performance optimization.
+   * @param monitor progress monitor to receive update status on.
+   * @throws IOException the database is unable to accept the update. This could be either caused by
+   *     one of the underlying update command or by the batch ref validator proving that the current
+   *     ref-db is not up-to-date with the global refdb
+   * @see BatchRefUpdate
+   * @see BatchRefUpdateValidator#executeBatchUpdateWithValidation(BatchRefUpdate,
+   *     RefUpdateValidator.NoParameterVoidFunction)
+   */
   @Override
   public void execute(RevWalk walk, ProgressMonitor monitor) throws IOException {
     batchRefValidatorFactory
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbConfiguration.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbConfiguration.java
index 1d5e023..a607cdc 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbConfiguration.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbConfiguration.java
@@ -17,6 +17,7 @@
 import static com.google.common.base.Suppliers.memoize;
 import static com.google.common.base.Suppliers.ofInstance;
 
+import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.SharedRefEnforcement;
 import com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb.SharedRefEnforcement.EnforcePolicy;
 import com.google.common.base.Supplier;
 import com.google.common.collect.ImmutableList;
@@ -30,6 +31,10 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Represents a configuration for the shared ref-database. This configuration is retrieved from the
+ * configuration file of the libModule is consuming the library.
+ */
 public class SharedRefDbConfiguration {
   private static final Logger log = LoggerFactory.getLogger(SharedRefDbConfiguration.class);
 
@@ -37,6 +42,13 @@
   private final Supplier<SharedRefDatabase> sharedRefDb;
   private final String pluginName;
 
+  /**
+   * Constructs a {@code SharedRefDbConfiguration} by providing the libModule name and a 'config'
+   * object
+   *
+   * @param config the libModule configuration
+   * @param pluginName the name of the libModule consuming this library
+   */
   public SharedRefDbConfiguration(Config config, String pluginName) {
     Supplier<Config> lazyCfg = lazyLoad(config);
     projects = memoize(() -> new Projects(lazyCfg));
@@ -44,14 +56,20 @@
     this.pluginName = pluginName;
   }
 
+  /**
+   * @return the {@link SharedRefDatabase} computed from the configuration libModule configuration
+   *     file
+   */
   public SharedRefDatabase getSharedRefDb() {
     return sharedRefDb.get();
   }
 
+  /** @return Getter of projects checked against the global refdb */
   public Projects projects() {
     return projects.get();
   }
 
+  /** @return name of the libModule consuming this library */
   public String pluginName() {
     return pluginName;
   }
@@ -74,6 +92,12 @@
     return ofInstance(config);
   }
 
+  /**
+   * Represents the global refdb configuration, which is computed by reading the 'ref-database'
+   * section from the configuration file of this library's consumers. It allows to specify whether
+   * it is enabled, specific {@link SharedRefEnforcement}s and to tune other parameters that define
+   * specific behaviours of the global refdb.
+   */
   public static class SharedRefDatabase {
     public static final String SECTION = "ref-database";
     public static final String ENABLE_KEY = "enabled";
@@ -91,10 +115,33 @@
       }
     }
 
+    /**
+     * Whether the use of the global refdb is enabled. Defaults 'false'
+     *
+     * @return true when enabled, false otherwise
+     */
     public boolean isEnabled() {
       return enabled;
     }
 
+    /**
+     * Getter for the map of {@link EnforcePolicy} to a specific "project:refs". Each entry can be
+     * either be {@link SharedRefEnforcement.EnforcePolicy#IGNORED} or {@link
+     * SharedRefEnforcement.EnforcePolicy#REQUIRED} and it represents the level of consistency
+     * enforcements for that specific "project:refs". If the project or ref is omitted, apply the
+     * policy to all projects or all refs.
+     *
+     * <p>The projec/ref will not be validated against the global refdb if it one to be ignored by
+     * default ({@link SharedRefEnforcement#isRefToBeIgnoredBySharedRefDb(String)} or if it has been
+     * configured so, for example:
+     *
+     * <pre>
+     *     [ref-database "enforcementRules"]
+     *    IGNORED = AProject:/refs/heads/feature
+     * </pre>
+     *
+     * @return Map of "project:refs" policies
+     */
     public Multimap<EnforcePolicy, String> getEnforcementRules() {
       return enforcementRules;
     }
@@ -105,15 +152,31 @@
     }
   }
 
+  /**
+   * Represents a set of projects for which ref updates operations should be validated against the
+   * global refdb. The list is computed from the consuming libModule's configuration file by looking
+   * at the "project.pattern" section. By defaults all projects are matched.
+   */
   public static class Projects {
     public static final String SECTION = "projects";
     public static final String PATTERN_KEY = "pattern";
     public List<String> patterns;
 
+    /**
+     * Constructs a {@code Projects} object by reading the list of "projects.pattern" possibly
+     * specified in the consuming libModule's configuration file.
+     *
+     * @param cfg the libModule's configuration supplier
+     */
     public Projects(Supplier<Config> cfg) {
       patterns = ImmutableList.copyOf(cfg.get().getStringList(SECTION, null, PATTERN_KEY));
     }
 
+    /**
+     * The list of project patterns read from the consuming libModule's configuration file.
+     *
+     * @return list of project patterns.
+     */
     public List<String> getPatterns() {
       return patterns;
     }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbGitRepositoryManager.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbGitRepositoryManager.java
index c8e7053..4f13d6e 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbGitRepositoryManager.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbGitRepositoryManager.java
@@ -27,9 +27,28 @@
 import org.eclipse.jgit.errors.RepositoryNotFoundException;
 import org.eclipse.jgit.lib.Repository;
 
+/**
+ * Implements a {@link GitRepositoryManager} interface with the intent of managing repository access
+ * and repository creation through instances of {@link SharedRefDbRepository}, which can therefore
+ * validate operations on the repository itself against the global refdb
+ */
 @Singleton
 public class SharedRefDbGitRepositoryManager implements GitRepositoryManager {
+  /**
+   * This value must be used for the named injection binding provided by libModules that want to
+   * define refs that should not be validated against the global refdb. For example:
+   *
+   * <pre>
+   *         bind(new TypeLiteral&lt;ImmutableSet&lt;String&gt;&gt;() {})
+   *         .annotatedWith(Names.named(SharedRefDbGitRepositoryManager.IGNORED_REFS))
+   *         .toInstance(
+   *             ImmutableSet.of(
+   *                 "refs/foo/bar",
+   *                 "refs/foo/baz"));
+   * </pre>
+   */
   public static final String IGNORED_REFS = "ignored_refs";
+
   private final GitRepositoryManager gitRepositoryManager;
   private final SharedRefDbRepository.Factory sharedRefDbRepoFactory;
 
@@ -37,6 +56,15 @@
   @Named(IGNORED_REFS)
   private ImmutableSet<String> ignoredRefs = ImmutableSet.of();
 
+  /**
+   * Constructs a {@code SharedRefDbGitRepositoryManager} that can create and open Git repositories
+   * by wrapping them in a {@code SharedRefDbRepository} object, so that operations on them can be
+   * validated against a global refdb
+   *
+   * @param sharedRefDbRepoFactory a factory providing a {@link SharedRefDbRepository} instance
+   * @param localDiskRepositoryManager an instance to manage repositories stored on the local file
+   *     system
+   */
   @Inject
   public SharedRefDbGitRepositoryManager(
       SharedRefDbRepository.Factory sharedRefDbRepoFactory,
@@ -45,12 +73,30 @@
     this.gitRepositoryManager = localDiskRepositoryManager;
   }
 
+  /**
+   * Get (or open) a {@link Repository} by name.
+   *
+   * @param name the repository name, relative to the base directory.
+   * @return the repository instance
+   * @throws RepositoryNotFoundException the name does not denote an existing repository.
+   * @throws IOException the name cannot be read as a repository.
+   */
   @Override
   public Repository openRepository(Project.NameKey name)
       throws RepositoryNotFoundException, IOException {
     return wrap(name, gitRepositoryManager.openRepository(name));
   }
 
+  /**
+   * Create (and open) a {@link Repository} by name.
+   *
+   * @param name the repository name, relative to the base directory.
+   * @return the repository instance
+   * @throws RepositoryCaseMismatchException the name collides with an existing repository name, but
+   *     only in case of a character within the name.
+   * @throws RepositoryNotFoundException the name is invalid.
+   * @throws IOException the repository cannot be created.
+   */
   @Override
   public Repository createRepository(Project.NameKey name)
       throws RepositoryCaseMismatchException, RepositoryNotFoundException, IOException {
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefDatabase.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefDatabase.java
index e3fde9c..8b51beb 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefDatabase.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefDatabase.java
@@ -27,6 +27,11 @@
 import org.eclipse.jgit.lib.RefRename;
 import org.eclipse.jgit.lib.RefUpdate;
 
+/**
+ * Wraps an instance of {@link RefDatabase} with the intent of wrapping {@link RefUpdate} operations
+ * to instances of {@link SharedRefDbRefUpdate} in order to allow validation of those operation
+ * against a shared ref-database before actually executing them.
+ */
 public class SharedRefDbRefDatabase extends RefDatabase {
   private final SharedRefDbRefUpdate.Factory refUpdateFactory;
   private final SharedRefDbBatchRefUpdate.Factory batchRefUpdateFactory;
@@ -34,11 +39,22 @@
   private final RefDatabase refDatabase;
   private final ImmutableSet<String> ignoredRefs;
 
+  /** {@code SharedRefDbRefDatabase} Factory for Guice assisted injection. */
   public interface Factory {
     SharedRefDbRefDatabase create(
         String projectName, RefDatabase refDatabase, ImmutableSet<String> ignoredRefs);
   }
 
+  /**
+   * Constructs a {@code SharedRefDbRefDatabase} by wrapping an underlying refDatabase, so that
+   * update refs operations can be validated against a shared ref-database.
+   *
+   * @param refUpdateFactory a factory to provide a {@link SharedRefDbRefUpdate}
+   * @param batchRefUpdateFactory a factory to provide a {@link SharedRefDbBatchRefUpdate}
+   * @param projectName the name of the project to perform Git operations on
+   * @param refDatabase the wrapped {@link RefDatabase}
+   * @param ignoredRefs a set of reference for which ref-db validation should not be executed.
+   */
   @Inject
   public SharedRefDbRefDatabase(
       SharedRefDbRefUpdate.Factory refUpdateFactory,
@@ -83,6 +99,13 @@
     return refDatabase.getConflictingNames(name);
   }
 
+  /**
+   * Wrap a {@link RefUpdate} obtained by calling the underlying {@link RefDatabase} in a {@link
+   * SharedRefDbRefUpdate}
+   *
+   * @see RefDatabase#newUpdate(String, boolean)
+   * @throws java.io.IOException the reference cannot be accessed.
+   */
   @Override
   public RefUpdate newUpdate(String name, boolean detach) throws IOException {
     return wrapRefUpdate(refDatabase.newUpdate(name, detach));
@@ -93,6 +116,13 @@
     return refDatabase.newRename(fromName, toName);
   }
 
+  /**
+   * Obtains a {@link SharedRefDbBatchRefUpdate} via the {@code BatchRefUpdate.Factory} invoked on
+   * the underlying {@link RefDatabase}, so that batch updates can be validated against the shared
+   * ref-db.
+   *
+   * @see RefDatabase#newUpdate(String, boolean)
+   */
   @Override
   public BatchRefUpdate newBatchUpdate() {
     return batchRefUpdateFactory.create(projectName, refDatabase, ignoredRefs);
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefUpdate.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefUpdate.java
index a461d83..9935c8d 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefUpdate.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRefUpdate.java
@@ -28,6 +28,10 @@
 import org.eclipse.jgit.revwalk.RevWalk;
 import org.eclipse.jgit.transport.PushCertificate;
 
+/**
+ * Creates, updates or deletes any reference after having checked the validity of this operation
+ * against the global refdb.
+ */
 public class SharedRefDbRefUpdate extends RefUpdate {
 
   protected final RefUpdate refUpdateBase;
@@ -35,6 +39,7 @@
   private final RefUpdateValidator.Factory refValidatorFactory;
   private final RefUpdateValidator refUpdateValidator;
 
+  /** {@code SharedRefDbRefUpdate} Factory for Guice assisted injection. */
   public interface Factory {
     SharedRefDbRefUpdate create(
         String projectName,
@@ -43,6 +48,17 @@
         ImmutableSet<String> ignoredRefs);
   }
 
+  /**
+   * Constructs a {@code SharedRefDbRefUpdate} to create, update or delete a reference in project
+   * projectName after validating the validity of the operation by an instance of {@code
+   * RefUpdateValidator}, which is {@link Inject}ed by Guice.
+   *
+   * @param refValidatorFactory factory for {@link RefUpdateValidator}
+   * @param projectName the name of the project being updated
+   * @param refUpdate the wrapped ref update operation
+   * @param refDb the mapping between refs and object ids
+   * @param ignoredRefs a list of refs for which to ignore validation for.
+   */
   @Inject
   public SharedRefDbRefUpdate(
       RefUpdateValidator.Factory refValidatorFactory,
@@ -96,21 +112,55 @@
     return notImplementedException();
   }
 
+  /**
+   * Update the ref to the new value, after checking its validity via {@link RefUpdateValidator}
+   *
+   * @return the result status of the update
+   * @throws IOException an error occurred when attempting to write the change, either for an
+   *     unexpected cause or because the validation failed and a split-brain was encountered or
+   *     prevented.
+   */
   @Override
   public Result update() throws IOException {
     return refUpdateValidator.executeRefUpdate(refUpdateBase, refUpdateBase::update);
   }
 
+  /**
+   * Update the ref to the new value, after checking its validity via {@link RefUpdateValidator}
+   *
+   * @param rev a RevWalk instance this update command can borrow to perform the merge test. The
+   *     walk will be reset to perform the test.
+   * @return the result status of the update
+   * @throws IOException an error occurred when attempting to write the change, either for an
+   *     unexpected cause or because the validation failed and a split-brain was encountered or
+   *     prevented.
+   */
   @Override
   public Result update(RevWalk rev) throws IOException {
     return refUpdateValidator.executeRefUpdate(refUpdateBase, () -> refUpdateBase.update(rev));
   }
 
+  /**
+   * Delete the ref after checking its validity via {@link RefUpdateValidator}
+   *
+   * @return the result status of the delete
+   * @throws IOException an error occurred when attempting to write the change, either for an
+   *     unexpected cause or because the validation failed and a split-brain was encountered or
+   *     prevented.
+   */
   @Override
   public Result delete() throws IOException {
     return refUpdateValidator.executeRefUpdate(refUpdateBase, refUpdateBase::delete);
   }
 
+  /**
+   * Delete the ref after checking its validity via {@link RefUpdateValidator}
+   *
+   * @param walk a RevWalk instance this delete command can borrow to perform the merge test. The
+   *     walk will be reset to perform the test.
+   * @return the result status of the delete
+   * @throws IOException deletion failed
+   */
   @Override
   public Result delete(RevWalk walk) throws IOException {
     return refUpdateValidator.executeRefUpdate(refUpdateBase, () -> refUpdateBase.delete(walk));
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRepository.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRepository.java
index 0e428fe..9e8bb9b 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRepository.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefDbRepository.java
@@ -23,15 +23,29 @@
 import org.eclipse.jgit.lib.RefUpdate;
 import org.eclipse.jgit.lib.Repository;
 
+/**
+ * Wrapper around a delegated Git repository {@link DelegateRepository}, which allows to intercept
+ * and proxy git operations through the global refdb to perform validation.
+ */
 public class SharedRefDbRepository extends DelegateRepository {
 
   private final SharedRefDbRefDatabase sharedRefDatabase;
 
+  /** {@code SharedRefDbRepository} Factory for Guice assisted injection. */
   public interface Factory {
     SharedRefDbRepository create(
         String projectName, Repository repository, ImmutableSet<String> ignoredRefs);
   }
 
+  /**
+   * Constructs a {@code SharedRefDbRepository} to validate git operation for projectName in {@code
+   * repository} against a shared refdb constructed via RefDBFactory
+   *
+   * @param refDbFactory a factory generating SharedRefDbRefDatabase ({@link Inject}ed by Guice)
+   * @param projectName the name of the project receiving the update
+   * @param repository the git repository
+   * @param ignoredRefs a set of references that do not need to be checked against the sared ref-db
+   */
   @Inject
   public SharedRefDbRepository(
       SharedRefDbRefDatabase.Factory refDbFactory,
@@ -43,16 +57,40 @@
         refDbFactory.create(projectName, repository.getRefDatabase(), ignoredRefs);
   }
 
+  /**
+   * Getter for the shared ref database
+   *
+   * @return {@link RefDatabase} the shared ref database
+   */
   @Override
   public RefDatabase getRefDatabase() {
     return sharedRefDatabase;
   }
 
+  /**
+   * Create a command to update, create or delete ref in this repository.
+   *
+   * @param ref name of the ref the caller wants to modify.
+   * @return an update command. The caller must finish populating this command and then invoke one
+   *     of the update methods to actually make a change.
+   * @throws java.io.IOException symbolic ref was passed in and could not be resolved back to the
+   *     base ref, as the symbolic ref could not be read.
+   */
   @Override
   public RefUpdate updateRef(String ref) throws IOException {
     return sharedRefDatabase.wrapRefUpdate(delegate.updateRef(ref));
   }
 
+  /**
+   * Create a command to update, create or delete ref in this repository.
+   *
+   * @param ref name of the ref the caller wants to modify.
+   * @param detach true to create a detached head
+   * @return an update command. The caller must finish populating this command and then invoke one
+   *     of the update methods to actually make a change.
+   * @throws java.io.IOException a symbolic ref was passed in and could not be resolved back to the
+   *     base ref, as the symbolic ref could not be read.
+   */
   @Override
   public RefUpdate updateRef(String ref, boolean detach) throws IOException {
     return sharedRefDatabase.wrapRefUpdate(delegate.updateRef(ref, detach));
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogEntry.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogEntry.java
index d580057..c72ab7c 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogEntry.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogEntry.java
@@ -17,7 +17,7 @@
 import com.google.gerrit.common.Nullable;
 import com.google.gerrit.extensions.common.GitPerson;
 
-public class SharedRefLogEntry {
+class SharedRefLogEntry {
 
   public enum Type {
     UPDATE_REF,
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogger.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogger.java
index faef27b..d2b1822 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogger.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/SharedRefLogger.java
@@ -19,13 +19,46 @@
 
 public interface SharedRefLogger {
 
+  /**
+   * Log the update of currRef in project project to ref newRefValue
+   *
+   * @param project the project the update is for
+   * @param currRef the ref being updated
+   * @param newRefValue the new value of the ref being updated
+   */
   void logRefUpdate(String project, Ref currRef, ObjectId newRefValue);
 
+  /**
+   * Log the update of currRef, pointed to by refName, in project 'project' to ref 'newRefValue'
+   *
+   * @param project the project the update is for
+   * @param refName the name of the ref being updatex
+   * @param currRef the current value of the ref being updated
+   * @param newRefValue the new value of the ref being updated
+   * @param <T> Type of the 'currRef' and the 'newRefValue'
+   */
   <T> void logRefUpdate(String project, String refName, T currRef, T newRefValue);
 
+  /**
+   * Log the deletion of 'project' from the global refdb
+   *
+   * @param project the project being deleted
+   */
   void logProjectDelete(String project);
 
+  /**
+   * Log the acquisition of a lock for the 'refName' of 'project'
+   *
+   * @param project the project containing the ref
+   * @param refName the name of the ref the lock is acquired for
+   */
   void logLockAcquisition(String project, String refName);
 
+  /**
+   * Log the releasing of a previously acquired lock for the 'refName' of 'project'
+   *
+   * @param project the project containing the ref
+   * @param refName the name of the ref the lock is being releaed for
+   */
   void logLockRelease(String project, String refName);
 }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ValidationMetrics.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ValidationMetrics.java
index 4cc10d2..583554c 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ValidationMetrics.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/ValidationMetrics.java
@@ -22,6 +22,12 @@
 import com.google.inject.Inject;
 import com.google.inject.Singleton;
 
+/**
+ * Creates and registers metrics related to ref-db validations, such as split brains events. Such
+ * metrics are exposed by Gerrit and can then be used for monitoring and alerting.
+ *
+ * <p>This class is a {@link Singleton} to ensure that metrics unique are only registered once.
+ */
 @Singleton
 public class ValidationMetrics {
   private static final String GIT_UPDATE_SPLIT_BRAIN_PREVENTED = "git_update_split_brain_prevented";
@@ -30,6 +36,13 @@
   private final Counter1<String> splitBrainPreventionCounter;
   private final Counter1<String> splitBrainCounter;
 
+  /**
+   * Constructs a new {@code ValidationMetrics}, by passing metricMaker and the global refdb
+   * configuration. Both parameters are bound and {@link Inject}ed by Guice.
+   *
+   * @param metricMaker Factory to create metrics for monitoring
+   * @param cfg Configuration of shared ref-database configuration file
+   */
   @Inject
   public ValidationMetrics(MetricMaker metricMaker, SharedRefDbConfiguration cfg) {
     this.splitBrainPreventionCounter =
@@ -49,10 +62,18 @@
                 "Ref-update operation left node in a split-brain scenario"));
   }
 
+  /**
+   * Increment the "git_update_split_brain_prevented" metric counter to signal that a split-brain
+   * event was prevented by performing validation against the global refdb.
+   */
   public void incrementSplitBrainPrevention() {
     splitBrainPreventionCounter.increment(GIT_UPDATE_SPLIT_BRAIN_PREVENTED);
   }
 
+  /**
+   * Increment the "git_update_split_brain" metric counter to signal that the current gerrit
+   * instance is in split-brain.
+   */
   public void incrementSplitBrain() {
     splitBrainCounter.increment(GIT_UPDATE_SPLIT_BRAIN);
   }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/CustomSharedRefEnforcementByProject.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/CustomSharedRefEnforcementByProject.java
index b1eca36..84f6a64 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/CustomSharedRefEnforcementByProject.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/CustomSharedRefEnforcementByProject.java
@@ -26,11 +26,21 @@
 import java.util.Iterator;
 import java.util.Map;
 
+/**
+ * Implementation of the {@link SharedRefEnforcement} interface which derives project and
+ * project/ref enforcement policy from the configuration of the libModule consuming this library
+ */
 public class CustomSharedRefEnforcementByProject implements SharedRefEnforcement {
   private static final String ALL = ".*";
 
   private final Supplier<Map<String, Map<String, EnforcePolicy>>> predefEnforcements;
 
+  /**
+   * Constructs a {@code CustomSharedRefEnforcementByProject} with the values specified in the
+   * configuration of the libModule consuming this library
+   *
+   * @param config the libModule configuration
+   */
   @Inject
   public CustomSharedRefEnforcementByProject(SharedRefDbConfiguration config) {
     this.predefEnforcements = memoize(() -> parseDryRunEnforcementsToMap(config));
@@ -71,6 +81,16 @@
     return value.trim().isEmpty() ? ALL : value;
   }
 
+  /**
+   * The enforcement policy for 'refName' in 'projectName' as computed from the libModule's
+   * configuration file.
+   *
+   * <p>By default all projects are REQUIRED to be consistent on all refs.
+   *
+   * @param projectName project to be enforced
+   * @param refName ref name to be enforced
+   * @return the enforcement policy for this project/ref
+   */
   @Override
   public EnforcePolicy getPolicy(String projectName, String refName) {
     if (isRefToBeIgnoredBySharedRefDb(refName)) {
@@ -91,6 +111,14 @@
         orDefault.getOrDefault(refName, orDefault.get(ALL)), EnforcePolicy.REQUIRED);
   }
 
+  /**
+   * The enforcement policy for 'projectName' as computed from the libModule's configuration file.
+   *
+   * <p>By default all projects are REQUIRED to be consistent on all refs.
+   *
+   * @param projectName the name of the project to get the policy for
+   * @return the enforcement policy for the project
+   */
   @Override
   public EnforcePolicy getPolicy(String projectName) {
     Map<String, EnforcePolicy> policiesForProject =
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/DefaultSharedRefEnforcement.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/DefaultSharedRefEnforcement.java
index 9c2ef35..ecff62f 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/DefaultSharedRefEnforcement.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/DefaultSharedRefEnforcement.java
@@ -14,13 +14,33 @@
 
 package com.gerritforge.gerrit.globalrefdb.validation.dfsrefdb;
 
+/**
+ * Default implementation of {@link SharedRefEnforcement}. This class provides the default
+ * project/ref enforcement rules when no more specific rules have been configured for the libModule
+ * consuming this library.
+ */
 public class DefaultSharedRefEnforcement implements SharedRefEnforcement {
 
+  /**
+   * Returns {@link EnforcePolicy#IGNORED} for refs to be ignored {@link
+   * SharedRefEnforcement#isRefToBeIgnoredBySharedRefDb(String)}, {@link EnforcePolicy#REQUIRED}
+   * otherwise
+   *
+   * @param projectName project to be enforced
+   * @param refName ref name to be enforced
+   * @return the policy for this project/ref
+   */
   @Override
   public EnforcePolicy getPolicy(String projectName, String refName) {
     return isRefToBeIgnoredBySharedRefDb(refName) ? EnforcePolicy.IGNORED : EnforcePolicy.REQUIRED;
   }
 
+  /**
+   * The global refdb validation policy for 'projectName'
+   *
+   * @param projectName project to be enforced
+   * @return always {@link EnforcePolicy#REQUIRED}
+   */
   @Override
   public EnforcePolicy getPolicy(String projectName) {
     return EnforcePolicy.REQUIRED;
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/NoopSharedRefDatabase.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/NoopSharedRefDatabase.java
index 4810c64..2a0f972 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/NoopSharedRefDatabase.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/NoopSharedRefDatabase.java
@@ -22,39 +22,105 @@
 import org.eclipse.jgit.lib.ObjectId;
 import org.eclipse.jgit.lib.Ref;
 
+/**
+ * Default implementation of the {@link GlobalRefDatabase} interface. accepts any refs without
+ * checking for consistency.
+ *
+ * <p>This is useful for setting up a test environment and allows multi-site library to be installed
+ * independently from any additional libModules or the existence of a specific Ref-DB installation.
+ */
 public class NoopSharedRefDatabase implements GlobalRefDatabase {
 
+  /**
+   * Project/ref is always considered up-to-date
+   *
+   * @param project project name of the ref
+   * @param ref to be checked against global ref-db
+   * @return true
+   * @throws GlobalRefDbLockException Never thrown by this implementation
+   */
   @Override
   public boolean isUpToDate(Project.NameKey project, Ref ref) throws GlobalRefDbLockException {
     return true;
   }
 
+  /**
+   * Put is always considered successful
+   *
+   * @param project project name of the ref
+   * @param currRef old value to compare to.
+   * @param newRefValue new reference to store.
+   * @return true
+   * @throws GlobalRefDbSystemError Never thrown by this implementation
+   */
   @Override
   public boolean compareAndPut(Project.NameKey project, Ref currRef, ObjectId newRefValue)
       throws GlobalRefDbSystemError {
     return true;
   }
 
+  /**
+   * Put is always considered unsuccessful
+   *
+   * @param project project name of the ref.
+   * @param refName to store the value for.
+   * @param currValue current expected value in the DB.
+   * @param newValue new value to store.
+   * @param <T> Type of the current and new value
+   * @return false
+   * @throws GlobalRefDbSystemError Never thrown by this implementation
+   */
   @Override
   public <T> boolean compareAndPut(Project.NameKey project, String refName, T currValue, T newValue)
       throws GlobalRefDbSystemError {
     return false;
   }
 
+  /**
+   * Locking the ref does nothing, but return an dummy {@link java.io.Closeable}.
+   *
+   * @param project project name
+   * @param refName ref to lock
+   * @return a dummy {@link java.io.Closeable}.
+   * @throws GlobalRefDbLockException Never thrown by this implementation
+   */
   @Override
   public AutoCloseable lockRef(Project.NameKey project, String refName)
       throws GlobalRefDbLockException {
     return () -> {};
   }
 
+  /**
+   * project/refs are always assumed to be new as to never be considered out-of-sync
+   *
+   * @param project project containing the ref
+   * @param refName the name of the ref
+   * @return false
+   */
   @Override
   public boolean exists(Project.NameKey project, String refName) {
     return false;
   }
 
+  /**
+   * Does nothing, the project is always considered to have been removed correctly from the shared
+   * ref-db.
+   *
+   * @param project project name
+   * @throws GlobalRefDbSystemError Never thrown by this implementation
+   */
   @Override
   public void remove(Project.NameKey project) throws GlobalRefDbSystemError {}
 
+  /**
+   * Always return an empty object as to never be considered existing in the global refdb.
+   *
+   * @param project project name
+   * @param refName reference name
+   * @param clazz wanted Class of the returned value
+   * @return {@link Optional#empty()}
+   * @throws GlobalRefDbSystemError Never thrown by this implementation
+   */
   @Override
   public <T> Optional<T> get(Project.NameKey project, String refName, Class<T> clazz)
       throws GlobalRefDbSystemError {
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedDbSplitBrainException.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedDbSplitBrainException.java
index aece4cb..dada134 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedDbSplitBrainException.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedDbSplitBrainException.java
@@ -16,13 +16,25 @@
 
 import java.io.IOException;
 
+/** Split-brain detected when trying to update a ref */
 public class SharedDbSplitBrainException extends IOException {
   private static final long serialVersionUID = 1L;
 
+  /**
+   * Constructs a {@code SharedDbSplitBrainException} with a message
+   *
+   * @param message details about the detected split brain
+   */
   public SharedDbSplitBrainException(String message) {
     super(message);
   }
 
+  /**
+   * Constructs a {@code SharedDbSplitBrainException} with a 'message' and a 'cause'
+   *
+   * @param message details about the detected split brain
+   * @param cause the cause of the split brain detection
+   */
   public SharedDbSplitBrainException(String message, Throwable cause) {
     super(message, cause);
   }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedLockException.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedLockException.java
index 69c3f33..5963da2 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedLockException.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedLockException.java
@@ -20,6 +20,14 @@
 public class SharedLockException extends IOException {
   private static final long serialVersionUID = 1L;
 
+  /**
+   * Constructs a {@code SharedLockException} exception with the cause of failing to lock a
+   * project/ref resource
+   *
+   * @param project the project the lock is being acquired for
+   * @param refName the ref the project is being acquired for
+   * @param cause the cause of the failure
+   */
   public SharedLockException(String project, String refName, Exception cause) {
     super(String.format("Unable to lock project %s on ref %s", project, refName), cause);
   }
diff --git a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedRefEnforcement.java b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedRefEnforcement.java
index d2c1ed6..a765975 100644
--- a/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedRefEnforcement.java
+++ b/src/main/java/com/gerritforge/gerrit/globalrefdb/validation/dfsrefdb/SharedRefEnforcement.java
@@ -33,15 +33,22 @@
   /**
    * Get the enforcement policy for a project
    *
-   * @param projectName
+   * @param projectName the name of the project
    * @return the {@link EnforcePolicy} value
    */
   public EnforcePolicy getPolicy(String projectName);
 
   /**
-   * Check if a refName should be ignored by shared Ref-Db
+   * Check if a refName should be ignored by global refdb. The Default behaviour is to ignore:
    *
-   * @param refName
+   * <ul>
+   *   <li>refs/draft-comments :user-specific temporary storage that does not need to be seen by
+   *       other users/sites
+   *   <li>refs/changes/&lt;non-meta&gt;: those refs are immutable
+   *   <li>refs/cache-automerge: these refs would be never replicated anyway
+   * </ul>
+   *
+   * @param refName the name of the ref to check
    * @return true if ref should be ignored; false otherwise
    */
   default boolean isRefToBeIgnoredBySharedRefDb(String refName) {