diff --git a/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java b/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java
index e86f62a136..cf58fc43c7 100644
--- a/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java
+++ b/scm-core/src/main/java/sonia/scm/store/BlobStoreFactory.java
@@ -35,8 +35,22 @@ package sonia.scm.store;
 import sonia.scm.repository.Repository;
 
 /**
- * The BlobStoreFactory can be used to create new or get existing
- * {@link BlobStore}s.
+ * The BlobStoreFactory can be used to create a new or get an existing {@link BlobStore}s.
+ * <br>
+ * You can either create a global {@link BlobStore} or a {@link BlobStore} for a specific repository. To create a global
+ * {@link BlobStore} call:
+ * <code><pre>
+ *     blobStoreFactory
+ *       .withName("name")
+ *       .build();
+ * </pre></code>
+ * To create a {@link BlobStore} for a specific repository call:
+ * <code><pre>
+ *     blobStoreFactory
+ *       .withName("name")
+ *       .forRepository(repository)
+ *       .build();
+ * </pre></code>
  *
  * @author Sebastian Sdorra
  * @since 1.23
@@ -46,8 +60,20 @@ import sonia.scm.repository.Repository;
  */
 public interface BlobStoreFactory {
 
+  /**
+   * Creates a new or gets an existing {@link BlobStore}. Instead of calling this method you should use the floating API
+   * from {@link #withName(String)}.
+   *
+   * @param storeParameters The parameters for the blob store.
+   * @return A new or an existing {@link BlobStore} for the given parameters.
+   */
   BlobStore getStore(final StoreParameters storeParameters);
 
+  /**
+   * Use this to create a new or get an existing {@link BlobStore} with a floating API.
+   * @param name The name for the {@link BlobStore}.
+   * @return Floating API to either specify a repository or directly build a global {@link BlobStore}.
+   */
   default FloatingStoreParameters.Builder withName(String name) {
     return new FloatingStoreParameters(this).new Builder(name);
   }
@@ -80,11 +106,21 @@ final class FloatingStoreParameters implements StoreParameters {
       FloatingStoreParameters.this.name = name;
     }
 
+    /**
+     * Use this to create or get a {@link BlobStore} for a specific repository. This step is optional. If you want to
+     * have a global {@link BlobStore}, omit this.
+     * @param repository The optional repository for the {@link BlobStore}.
+     * @return Floating API to finish the call.
+     */
     public FloatingStoreParameters.Builder forRepository(Repository repository) {
       FloatingStoreParameters.this.repository = repository;
       return this;
     }
 
+    /**
+     * Creates or gets the {@link BlobStore} with the given name and (if specified) the given repository. If no
+     * repository is given, the {@link BlobStore} will be global.
+     */
     public BlobStore build(){
       return factory.getStore(FloatingStoreParameters.this);
     }
diff --git a/scm-core/src/main/java/sonia/scm/store/ConfigurationEntryStoreFactory.java b/scm-core/src/main/java/sonia/scm/store/ConfigurationEntryStoreFactory.java
index b77eb2c0f1..80f9cb3df9 100644
--- a/scm-core/src/main/java/sonia/scm/store/ConfigurationEntryStoreFactory.java
+++ b/scm-core/src/main/java/sonia/scm/store/ConfigurationEntryStoreFactory.java
@@ -35,12 +35,28 @@ package sonia.scm.store;
 import sonia.scm.repository.Repository;
 
 /**
- * The ConfigurationEntryStoreFactory can be used to create new or get existing
- * {@link ConfigurationEntryStore}s.
+ * The ConfigurationEntryStoreFactory can be used to create new or get existing {@link ConfigurationEntryStore}s.
+ * <br>
+ * <b>Note:</b> the default implementation uses the same location as the {@link ConfigurationStoreFactory}, so be sure
+ * that the store names are unique for all {@link ConfigurationEntryStore}s and {@link ConfigurationEntryStore}s.
+ * <br>
+ * You can either create a global {@link ConfigurationEntryStore} or a {@link ConfigurationEntryStore} for a specific
+ * repository. To create a global {@link ConfigurationEntryStore} call:
+ * <code><pre>
+ *     configurationEntryStoreFactory
+ *       .withType(PersistedType.class)
+ *       .withName("name")
+ *       .build();
+ * </pre></code>
+ * To create a {@link ConfigurationEntryStore} for a specific repository call:
+ * <code><pre>
+ *     configurationEntryStoreFactory
+ *       .withType(PersistedType.class)
+ *       .withName("name")
+ *       .forRepository(repository)
+ *       .build();
+ * </pre></code>
  *
- * <b>Note:</b> the default implementation uses the same location as the {@link ConfigurationStoreFactory}, so be sure that the
- * store names are unique for all {@link ConfigurationEntryStore}s and {@link ConfigurationStore}s.
- * 
  * @author Sebastian Sdorra
  * @since 1.31
  * 
@@ -48,8 +64,22 @@ import sonia.scm.repository.Repository;
  * @apiviz.uses sonia.scm.store.ConfigurationEntryStore
  */
 public interface ConfigurationEntryStoreFactory {
+
+  /**
+   * Creates a new or gets an existing {@link ConfigurationEntryStore}. Instead of calling this method you should use
+   * the floating API from {@link #withType(Class)}.
+   *
+   * @param storeParameters The parameters for the {@link ConfigurationEntryStore}.
+   * @return A new or an existing {@link ConfigurationEntryStore} for the given parameters.
+   */
   <T> ConfigurationEntryStore<T> getStore(final TypedStoreParameters<T> storeParameters);
 
+  /**
+   * Use this to create a new or get an existing {@link ConfigurationEntryStore} with a floating API.
+   * @param type The type for the {@link ConfigurationEntryStore}.
+   * @return Floating API to set the name and either specify a repository or directly build a global
+   * {@link ConfigurationEntryStore}.
+   */
   default <T> TypedFloatingConfigurationEntryStoreParameters<T>.Builder withType(Class<T> type) {
     return new TypedFloatingConfigurationEntryStoreParameters<T>(this).new Builder(type);
   }
@@ -70,6 +100,11 @@ final class TypedFloatingConfigurationEntryStoreParameters<T> {
       parameters.setType(type);
     }
 
+    /**
+     * Use this to set the name for the {@link ConfigurationEntryStore}.
+     * @param name The name for the {@link ConfigurationEntryStore}.
+     * @return Floating API to either specify a repository or directly build a global {@link ConfigurationEntryStore}.
+     */
     public OptionalRepositoryBuilder withName(String name) {
       parameters.setName(name);
       return new OptionalRepositoryBuilder();
@@ -78,11 +113,21 @@ final class TypedFloatingConfigurationEntryStoreParameters<T> {
 
   public class OptionalRepositoryBuilder {
 
+    /**
+     * Use this to create or get a {@link ConfigurationEntryStore} for a specific repository. This step is optional. If
+     * you want to have a global {@link ConfigurationEntryStore}, omit this.
+     * @param repository The optional repository for the {@link ConfigurationEntryStore}.
+     * @return Floating API to finish the call.
+     */
     public OptionalRepositoryBuilder forRepository(Repository repository) {
       parameters.setRepository(repository);
       return this;
     }
 
+    /**
+     * Creates or gets the {@link ConfigurationEntryStore} with the given name and (if specified) the given repository.
+     * If no repository is given, the {@link ConfigurationEntryStore} will be global.
+     */
     public ConfigurationEntryStore<T> build(){
       return factory.getStore(parameters);
     }
diff --git a/scm-core/src/main/java/sonia/scm/store/ConfigurationStoreFactory.java b/scm-core/src/main/java/sonia/scm/store/ConfigurationStoreFactory.java
index 55a6baf83d..6624f307e7 100644
--- a/scm-core/src/main/java/sonia/scm/store/ConfigurationStoreFactory.java
+++ b/scm-core/src/main/java/sonia/scm/store/ConfigurationStoreFactory.java
@@ -36,11 +36,27 @@ package sonia.scm.store;
 import sonia.scm.repository.Repository;
 
 /**
- * The ConfigurationStoreFactory can be used to create new or get existing 
- * {@link ConfigurationStore} objects.
- *
- * <b>Note:</b> the default implementation uses the same location as the {@link ConfigurationEntryStoreFactory}, so be sure that the
- *  store names are unique for all {@link ConfigurationEntryStore}s and {@link ConfigurationStore}s.
+ * The ConfigurationStoreFactory can be used to create new or get existing {@link ConfigurationStore} objects.
+ * <br>
+ * <b>Note:</b> the default implementation uses the same location as the {@link ConfigurationEntryStoreFactory}, so be
+ * sure that the store names are unique for all {@link ConfigurationEntryStore}s and {@link ConfigurationStore}s.
+ * <br>
+ * You can either create a global {@link ConfigurationStore} or a {@link ConfigurationStore} for a specific repository.
+ * To create a global {@link ConfigurationStore} call:
+ * <code><pre>
+ *     configurationStoreFactory
+ *       .withType(PersistedType.class)
+ *       .withName("name")
+ *       .build();
+ * </pre></code>
+ * To create a {@link ConfigurationStore} for a specific repository call:
+ * <code><pre>
+ *     configurationStoreFactory
+ *       .withType(PersistedType.class)
+ *       .withName("name")
+ *       .forRepository(repository)
+ *       .build();
+ * </pre></code>
  *
  * @author Sebastian Sdorra
  * 
@@ -48,8 +64,22 @@ import sonia.scm.repository.Repository;
  * @apiviz.uses sonia.scm.store.ConfigurationStore
  */
 public interface ConfigurationStoreFactory  {
+
+  /**
+   * Creates a new or gets an existing {@link ConfigurationStore}. Instead of calling this method you should use the
+   * floating API from {@link #withType(Class)}.
+   *
+   * @param storeParameters The parameters for the {@link ConfigurationStore}.
+   * @return A new or an existing {@link ConfigurationStore} for the given parameters.
+   */
   <T> ConfigurationStore<T> getStore(final TypedStoreParameters<T> storeParameters);
 
+  /**
+   * Use this to create a new or get an existing {@link ConfigurationStore} with a floating API.
+   * @param type The type for the {@link ConfigurationStore}.
+   * @return Floating API to set the name and either specify a repository or directly build a global
+   * {@link ConfigurationStore}.
+   */
   default <T> TypedFloatingConfigurationStoreParameters<T>.Builder withType(Class<T> type) {
     return new TypedFloatingConfigurationStoreParameters<T>(this).new Builder(type);
   }
@@ -70,6 +100,11 @@ final class TypedFloatingConfigurationStoreParameters<T> {
       parameters.setType(type);
     }
 
+    /**
+     * Use this to set the name for the {@link ConfigurationStore}.
+     * @param name The name for the {@link ConfigurationStore}.
+     * @return Floating API to either specify a repository or directly build a global {@link ConfigurationStore}.
+     */
     public OptionalRepositoryBuilder withName(String name) {
       parameters.setName(name);
       return new OptionalRepositoryBuilder();
@@ -78,11 +113,21 @@ final class TypedFloatingConfigurationStoreParameters<T> {
 
   public class OptionalRepositoryBuilder {
 
+    /**
+     * Use this to create or get a {@link ConfigurationStore} for a specific repository. This step is optional. If you
+     * want to have a global {@link ConfigurationStore}, omit this.
+     * @param repository The optional repository for the {@link ConfigurationStore}.
+     * @return Floating API to finish the call.
+     */
     public OptionalRepositoryBuilder forRepository(Repository repository) {
       parameters.setRepository(repository);
       return this;
     }
 
+    /**
+     * Creates or gets the {@link ConfigurationStore} with the given name and (if specified) the given repository. If no
+     * repository is given, the {@link ConfigurationStore} will be global.
+     */
     public ConfigurationStore<T> build(){
       return factory.getStore(parameters);
     }
diff --git a/scm-core/src/main/java/sonia/scm/store/DataStoreFactory.java b/scm-core/src/main/java/sonia/scm/store/DataStoreFactory.java
index bb2f0a37ad..564c339d3d 100644
--- a/scm-core/src/main/java/sonia/scm/store/DataStoreFactory.java
+++ b/scm-core/src/main/java/sonia/scm/store/DataStoreFactory.java
@@ -35,8 +35,24 @@ package sonia.scm.store;
 import sonia.scm.repository.Repository;
 
 /**
- * The DataStoreFactory can be used to create new or get existing
- * {@link DataStore}s.
+ * The DataStoreFactory can be used to create new or get existing {@link DataStore}s.
+ * <br>
+ * You can either create a global {@link DataStore} or a {@link DataStore} for a specific repository.
+ * To create a global {@link DataStore} call:
+ * <code><pre>
+ *     dataStoreFactory
+ *       .withType(PersistedType.class)
+ *       .withName("name")
+ *       .build();
+ * </pre></code>
+ * To create a {@link DataStore} for a specific repository call:
+ * <code><pre>
+ *     dataStoreFactory
+ *       .withType(PersistedType.class)
+ *       .withName("name")
+ *       .forRepository(repository)
+ *       .build();
+ * </pre></code>
  *
  * @author Sebastian Sdorra
  * @since 1.23
@@ -45,8 +61,22 @@ import sonia.scm.repository.Repository;
  * @apiviz.uses sonia.scm.store.DataStore
  */
 public interface DataStoreFactory {
+
+  /**
+   * Creates a new or gets an existing {@link DataStore}. Instead of calling this method you should use the
+   * floating API from {@link #withType(Class)}.
+   *
+   * @param storeParameters The parameters for the {@link DataStore}.
+   * @return A new or an existing {@link DataStore} for the given parameters.
+   */
   <T> DataStore<T> getStore(final TypedStoreParameters<T> storeParameters);
 
+  /**
+   * Use this to create a new or get an existing {@link DataStore} with a floating API.
+   * @param type The type for the {@link DataStore}.
+   * @return Floating API to set the name and either specify a repository or directly build a global
+   * {@link DataStore}.
+   */
   default <T> TypedFloatingDataStoreParameters<T>.Builder withType(Class<T> type) {
     return new TypedFloatingDataStoreParameters<T>(this).new Builder(type);
   }
@@ -67,6 +97,11 @@ final class TypedFloatingDataStoreParameters<T> {
       parameters.setType(type);
     }
 
+    /**
+     * Use this to set the name for the {@link DataStore}.
+     * @param name The name for the {@link DataStore}.
+     * @return Floating API to either specify a repository or directly build a global {@link DataStore}.
+     */
     public OptionalRepositoryBuilder withName(String name) {
       parameters.setName(name);
       return new OptionalRepositoryBuilder();
@@ -75,11 +110,21 @@ final class TypedFloatingDataStoreParameters<T> {
 
   public class OptionalRepositoryBuilder {
 
+    /**
+     * Use this to create or get a {@link DataStore} for a specific repository. This step is optional. If you
+     * want to have a global {@link DataStore}, omit this.
+     * @param repository The optional repository for the {@link DataStore}.
+     * @return Floating API to finish the call.
+     */
     public OptionalRepositoryBuilder forRepository(Repository repository) {
       parameters.setRepository(repository);
       return this;
     }
 
+    /**
+     * Creates or gets the {@link DataStore} with the given name and (if specified) the given repository. If no
+     * repository is given, the {@link DataStore} will be global.
+     */
     public DataStore<T> build(){
       return factory.getStore(parameters);
     }