diff --git a/documentation/src/main/docbook/en-US/modules/advanced-features.xml b/documentation/src/main/docbook/en-US/modules/advanced-features.xml
index e420cc3a703..cd4ed523354 100644
--- a/documentation/src/main/docbook/en-US/modules/advanced-features.xml
+++ b/documentation/src/main/docbook/en-US/modules/advanced-features.xml
@@ -281,6 +281,13 @@ finally {
query (getShardIdentifiersForQuery(), not shown
in the example) and thus speed up the query execution.
+
+ This ShardIdentifierProvider is considered
+ experimental. We might need to apply some changes to the defined method
+ signatures to accomodate for unforeseen use cases. Please provide
+ feedback if you have ideas, or just to let us know how you're using
+ this API.
+
diff --git a/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProvider.java b/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProvider.java
index 695c83a5fc9..3200e41587c 100644
--- a/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProvider.java
+++ b/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProvider.java
@@ -41,6 +41,8 @@
* Instead of implementing this interface directly, implementations should be derived from
* {@link ShardIdentifierProviderTemplate} as new methods might be added to this interface in future releases.
*
+ * @experimental The exact method signatures are likely to change in future.
+ *
* @author Emmanuel Bernard
* @author Hardy Ferentschik
* @author Sanne Grinovero (C) 2013 Red Hat Inc.
@@ -100,7 +102,7 @@ public interface ShardIdentifierProvider {
* {@link #getShardIdentifier(Class, Serializable, String, Document)}, {@link #getShardIdentifiersForQuery(FullTextFilterImplementor[])},
* {@link #getAllShardIdentifiers()}.
*
- * @return the list of all currently known shard identifiers.
+ * @return the set of all currently known shard identifiers.
*/
Set getAllShardIdentifiers();
}
diff --git a/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProviderTemplate.java b/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProviderTemplate.java
index 4ecf2f89a66..a310b37f428 100644
--- a/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProviderTemplate.java
+++ b/engine/src/main/java/org/hibernate/search/store/ShardIdentifierProviderTemplate.java
@@ -32,6 +32,8 @@
* Recommended parent class to create custom {@link ShardIdentifierProvider} implementations. Sub-classes must provide a
* no-arg constructor.
*
+ * @experimental The exact method signatures are likely to change in future.
+ *
* @author Sanne Grinovero
*/
public abstract class ShardIdentifierProviderTemplate implements ShardIdentifierProvider {