This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git
The following commit(s) were added to refs/heads/2.3-gae by this push:
new 14f651f5 Further javadoc fixes/improvements related to
CFormat-s/?c/?cn.
14f651f5 is described below
commit 14f651f5bc9f85d57e75b53a219b41f6f5d14318
Author: ddekany <ddek...@apache.org>
AuthorDate: Thu Dec 29 02:55:37 2022 +0100
Further javadoc fixes/improvements related to CFormat-s/?c/?cn.
---
src/main/java/freemarker/core/CFormat.java | 4 +--
src/main/java/freemarker/core/Configurable.java | 2 +-
src/main/java/freemarker/core/XSCFormat.java | 7 +++++
.../java/freemarker/template/Configuration.java | 32 +++++++++++++++-------
4 files changed, 32 insertions(+), 13 deletions(-)
diff --git a/src/main/java/freemarker/core/CFormat.java
b/src/main/java/freemarker/core/CFormat.java
index f5a2c84e..d9d0cca8 100644
--- a/src/main/java/freemarker/core/CFormat.java
+++ b/src/main/java/freemarker/core/CFormat.java
@@ -25,8 +25,8 @@ import freemarker.template.TemplateException;
/**
* Defines a format (usually a computer language) that's used by the {@code
c}, {@code cn} built-ins, and for the
- * {@code "c"} and {@code "computer"} {@link
Configurable#setNumberFormat(String)} number_format), and
- * the {@code "c"} {@link Configurable#setBooleanFormat(String)}
boolean_format}.
+ * {@code "c"} and {@code "computer"} {@link
Configurable#setNumberFormat(String) number_format}, and
+ * the {@code "c"} {@link Configurable#setBooleanFormat(String)
boolean_format}.
* A {@link CFormat} currently defines how numbers, booleans, and strings are
converted to text that defines a similar
* value in some computer language (or other computer-parsed syntax) that the
{@link CFormat} is made for.
*
diff --git a/src/main/java/freemarker/core/Configurable.java
b/src/main/java/freemarker/core/Configurable.java
index 71339145..6da2b48c 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -698,7 +698,7 @@ public class Configurable {
/**
* Sets the format (usually a computer language) used for the {@code c},
{@code cn} built-ins, and for the
- * {@code "c"} {@code "computer"} before 2.3.32) {@link
#setNumberFormat(String) number_format}, and the
+ * {@code "c"} ({@code "computer"} before 2.3.32) {@link
#setNumberFormat(String) number_format}, and the
* {@code "c"} {@link #setBooleanFormat(String) boolean_format}.
*
* <p>The default value depends on {@link
Configuration#Configuration(Version) incompatible_improvements}.
diff --git a/src/main/java/freemarker/core/XSCFormat.java
b/src/main/java/freemarker/core/XSCFormat.java
index 67da2d8f..9d602c09 100644
--- a/src/main/java/freemarker/core/XSCFormat.java
+++ b/src/main/java/freemarker/core/XSCFormat.java
@@ -28,9 +28,16 @@ import freemarker.template.TemplateException;
/**
* {@value #NAME} {@link CFormat}, for outputting XML that follows the
conventions of XML Schema.
*
+ * <p>Note that with this, strings formatted with {@code ?c}/{@code ?cn}
aren't quoted, or escaped with backslash, since
+ * those are meaningless in XML, as far as XML Schema is concerned. They are
just printed without change. (Note that
+ * XML-escaping is the duty of the auto-escaping facility of FreeMarker, and
not of the {@link CFormat}, so that's not
+ * done here either.)
+ *
* <p><b>Experimental class!</b> This class is too new, and might will change
over time. Therefore, for now the
* most methods are not exposed outside FreeMarker. The class itself and some
members are exposed as they are needed for
* configuring FreeMarker.
+ *
+ * @since 2.3.32
*/
public final class XSCFormat extends CFormat {
public static final String NAME = "XS";
diff --git a/src/main/java/freemarker/template/Configuration.java
b/src/main/java/freemarker/template/Configuration.java
index b2d34a21..05385ea7 100644
--- a/src/main/java/freemarker/template/Configuration.java
+++ b/src/main/java/freemarker/template/Configuration.java
@@ -82,6 +82,7 @@ import freemarker.core.UndefinedOutputFormat;
import freemarker.core.UnregisteredOutputFormatException;
import freemarker.core.XHTMLOutputFormat;
import freemarker.core.XMLOutputFormat;
+import freemarker.core.XSCFormat;
import freemarker.core._CoreAPI;
import freemarker.core._DelayedJQuote;
import freemarker.core._MiscTemplateException;
@@ -479,7 +480,7 @@ public class Configuration extends Configurable implements
Cloneable, ParserConf
/** FreeMarker version 2.3.31 (an {@link #Configuration(Version)
incompatible improvements break-point}) */
public static final Version VERSION_2_3_31 = new Version(2, 3, 31);
- /** FreeMarker version 2.3.31 (an {@link #Configuration(Version)
incompatible improvements break-point}) */
+ /** FreeMarker version 2.3.32 (an {@link #Configuration(Version)
incompatible improvements break-point}) */
public static final Version VERSION_2_3_32 = new Version(2, 3, 32);
/** The default of {@link #getIncompatibleImprovements()}, currently
{@link #VERSION_2_3_0}. */
@@ -953,15 +954,26 @@ public class Configuration extends Configurable
implements Cloneable, ParserConf
* <li><p>
* 2.3.32 (or higher):
* <ul>
- * <li><p>The "computer" formatting of numbers (this is what {@code
?c} does, also setting the
- * {@code number_format} to {@code "c"}, or to {@code "computer"})
has changed for some non-whole numbers, and
- * for whole numbers with over 100 digits. It's now lossless, so it
potentially shows much more decimals. It
- * uses exponential format (like 1.2E-7 instead of 0.00000012) for
numbers whose absolute value is less
- * than 1E-6 (0.000001), and for whole numbers whose absolute value
is at least 1E101 (so over 100 digits).
- * It also uses exponential format for whole floating point ({@code
double}/{@code Double}}, or
- * {@code float}/{@code Float}) numbers, when their absolute value
is too big for the floating point type to
- * store them precisely (so if the intent was to store some ID-s,
they are likely corrupted anyway, as the
- * type skips some whole numbers).
+ * <li><p>
+ * The number formatting of {@code ?c}, {@code ?cn}, and if the
{@code "c"} and {@code "computer"}
+ * {@link Configurable#setNumberFormat(String) number_format}
changes, if the
+ * {@link #setCFormat(CFormat) c_format} was left on its default
(because the default of that changes to
+ * {@link JavaScriptOrJSONCFormat#INSTANCE}, from {@link
Default2321CFormat#INSTANCE}):
+ * <ul>
+ * <li><p>Changes affecting non-whole numbers, and for whole
numbers with over 100 digits:
+ * Formatting is now lossless, so it potentially shows much
more decimals.
+ * It now uses exponential format (like 1.2E-7 instead of
0.00000012) for numbers whose absolute value
+ * is less than 1E-6 (0.000001), and for whole numbers whose
absolute value is at least 1E101 (so over
+ * 100 digits). It also uses exponential format for whole
floating point
+ * ({@code double}/{@code Double}}, or {@code float}/{@code
Float}) numbers, when their absolute value
+ * is too big for the floating point type to store them
precisely (so if the intent was to store some
+ * ID-s, they are likely corrupted anyway, as the type skips
some whole numbers).</p></li>
+ * <li><p>Changes floating point infinity format from {@code
INF} to {@code Infinity}, which is the
+ * JavaScript and JSON syntax. If you generate XML with
XSD-style number syntax (which uses
+ * {@code INF}), but you want the other number formatting
changes (recommended), then set
+ * {@link #setCFormat(CFormat) c_format} to {@link
XSCFormat#INSTANCE}/{@code "XS"}.</p></li>
+ * </ul>
+ * </li>
* </ul>
* </li>
* </ul>
