Fix #1351: Improved Javadocs for StreamWriteFeature.USE_FAST_DOUBLE_WRITER

cowtowncoder · cowtowncoder · commit cbedab7ddf0c · 2024-10-23T20:38:45.000-07:00
diff --git a/src/main/java/com/fasterxml/jackson/core/StreamWriteFeature.java b/src/main/java/com/fasterxml/jackson/core/StreamWriteFeature.java
@@ -115,11 +115,17 @@ public enum StreamWriteFeature
 
     /**
      * Feature that determines whether to use standard Java code to write floats/doubles
-     * (default) or use the Schubfach algorithm which is faster.
-     * The latter approach may lead to small differences in the precision of the
-     * float/double that is written to the JSON output.
+     * (default) or use the Schubfach algorithm which may be faster (but see the next
+     * paragraph for details).
+     * Schubfach algorithm output may have small differences in the precision of the
+     * float/double that compared to JDK default processing.
      *<p>
-     * Feature is disabled by default, meaning that slower JDK default conversions are used.
+     * NOTE! Enabling this feature appears to improve performance significantly
+     * up to and including JDK 17, but NOT when using JDK 21
+     * and above -- in fact, it seems that JDK implementation is slightly faster.
+     * Because of this,enabling this feature is only recommended for JDKs 17 and below.
+     *<p>
+     * Feature is disabled by default, meaning that JDK default conversions are used.
      *
      * @since 2.14
      */
