diff --git a/lucene/codecs/src/java/org/apache/lucene/codecs/compressing/CompressingStoredFieldsFormat.java b/lucene/codecs/src/java/org/apache/lucene/codecs/compressing/CompressingStoredFieldsFormat.java
index bcd8480eb91..6034c483534 100644
--- a/lucene/codecs/src/java/org/apache/lucene/codecs/compressing/CompressingStoredFieldsFormat.java
+++ b/lucene/codecs/src/java/org/apache/lucene/codecs/compressing/CompressingStoredFieldsFormat.java
@@ -32,7 +32,12 @@ import org.apache.lucene.store.IOContext;
 /**
  * A {@link StoredFieldsFormat} that is very similar to
  * {@link Lucene40StoredFieldsFormat} but compresses documents in chunks in
- * order to improve compression ratio.
+ * order to improve the compression ratio.
+ * <p>
+ * For a chunk size of <tt>chunkSize</tt> bytes, this {@link StoredFieldsFormat}
+ * does not support documents larger than (<tt>2<sup>31</sup> - chunkSize</tt>)
+ * bytes. In case this is a problem, you should use another format, such as
+ * {@link Lucene40StoredFieldsFormat}.
  * <p>
  * For optimal performance, you should use a {@link MergePolicy} that returns
  * segments that have the biggest byte size first.