Add release notes wrt #733, minor tweaks to Javadoc

Author: cowtowncoder

release-notes/CREDITS-2.x

@@ -163,6 +163,9 @@ Doug Roper (htmldoug@github)
   (2.9.6)
   * Reported, Contributed test for #563: Async parser does not keep track of Array context properly
   (2.10.0)
+  * Contributed #733: Add `StreamReadCapability.EXACT_FLOATS` to indicate whether parser reports exact
+  floating-point values or not
+  (2.14.0)
 
 Alexander Eyers-Taylor (aeyerstaylor@github)
   * Reported #510: Fix ArrayIndexOutofBoundsException found by LGTM.com

release-notes/VERSION-2.x

@@ -20,6 +20,9 @@ JSON library.
  (contributed by Ilya G)
 #715: Allow TokenFilters to keep empty arrays and objects
  (contributed by Nik E)
+#733: Add `StreamReadCapability.EXACT_FLOATS` to indicate whether parser reports exact
+  floating-point values or not
+ (contributed Doug R)
 
 2.13.2 (not yet released)
 

src/main/java/com/fasterxml/jackson/core/StreamReadCapability.java

@@ -50,19 +50,39 @@ public enum StreamReadCapability
     UNTYPED_SCALARS(false),
 
     /**
-     * Capability that indicates that data format may report floats
-     * as a non-exact {@link com.fasterxml.jackson.core.JsonParser.NumberType},
-     * due to prohibitively expensive parsing costs of determing the precision
-     * upfront. For example, JSON numbers may be reported as
-     * {@link com.fasterxml.jackson.core.JsonParser.NumberType#DOUBLE}
-     * even if they would not fit into a 64-bit double without precision
-     * loss. Methods like {@link JsonParser#getNumberValueExact()} or
-     * {@link JsonParser#getValueAsString()} still report values without
+     * Capability that indicates whether data format supports reporting of
+     * accurate floating point values (with respect to reported numeric type,
+     * {@link com.fasterxml.jackson.core.JsonParser.NumberType#DOUBLE}) or not.
+     * This usually depends on whether format stores such values natively
+     * (as IEEE binary FP formats for {@code java.lang.Float} and {@code java.lang.Double};
+     * using some other value preserving presentation for {@code java.math.BigDecimal})
+     * or not: most binary formats do, and most textual formats do not (at least for
+     * {@code Float} and {@code Double}, specifically).
+     *<p>
+     * In case of JSON numbers (as well as for most if not all textual formats),
+     * all floating-point numbers are represented simply by decimal (10-base)
+     * textual representation and can only be represented accurately using
+     * {@link java.math.BigDecimal}. But for performance reasons they may be
+     * (depending on settings) be exposed as {@link java.lang.Double}s (that is,
+     * {@link com.fasterxml.jackson.core.JsonParser.NumberType#DOUBLE}).
+     * Note that methods like {@link JsonParser#getNumberValueExact()},
+     * {@link JsonParser#getValueAsString()} and
+     * {@link JsonParser#getDecimalValue()} report values without
      * precision loss.
-     *
-     * Capability is false for text formats JSON, but true for binary formats
+     *<p>
+     * The main intended use case is to let non-Jackson code to handle cases
+     * where exact accuracy is necessary in a way that handling does not incur
+     * unnecessary conversions across different formats: for example, when reading
+     * binary format, simple access is essentially guaranteed to expose value exactly
+     * as encoded by the format (as {@code float}, {@code double} or {@code BigDecimal}),
+     * whereas for textual formats like JSON it is necessary to access value explicitly
+     * as {@code BigDecimal} using {@code JsonParser#getDecimalValue}.
+     *<p>
+     * Capability is false for text formats like JSON, but true for binary formats
      * like Smile, MessagePack, etc., where type is precisely and inexpensively
-     * signaled by a tag.
+     * indicated by format.
+     *
+     * @since 2.14
      */
     EXACT_FLOATS(false)
     ;