diff --git a/lucene/core/src/java/org/apache/lucene/analysis/package-info.java b/lucene/core/src/java/org/apache/lucene/analysis/package-info.java
index 81858df198d..a536f73fc16 100644
--- a/lucene/core/src/java/org/apache/lucene/analysis/package-info.java
+++ b/lucene/core/src/java/org/apache/lucene/analysis/package-info.java
@@ -362,11 +362,13 @@
*
*
* - Inhibiting phrase and proximity matches in sentence boundaries – for this, a tokenizer that
- * identifies a new sentence can add 1 to the position increment of the first token of the new sentence.
- * - Injecting synonyms – here, synonyms of a token should be added after that token,
- * and their position increment should be set to 0.
- * As result, all synonyms of a token would be considered to appear in exactly the
- * same position as that token, and so would they be seen by phrase and proximity searches.
+ * identifies a new sentence can add 1 to the position increment of the first token of the new sentence.
+ * - Injecting synonyms – synonyms of a token should be created at the same position as the
+ * original token, and the output order of the original token and the injected synonym is undefined
+ * as long as they both leave from the same position. As result, all synonyms of a token would be
+ * considered to appear in exactly the same position as that token, and so would they be seen by
+ * phrase and proximity searches. For multi-token synonyms to work correctly, you should use
+ * {@code SynoymGraphFilter} at search time only.
*
*
* Token Position Length