[freemarker] 01/02: (Javadoc adjustments)

[dd...@apache.org]

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

commit f3d9d89e59c882c12e4c04b5e20524ec127ba43d
Author: ddekany <dd...@apache.org>
AuthorDate: Mon Dec 19 18:45:05 2022 +0100

    (Javadoc adjustments)
---
 src/main/java/freemarker/core/CommonMarkupOutputFormat.java  | 10 ++++++++++
 src/main/java/freemarker/core/MarkupOutputFormat.java        |  8 ++++----
 src/main/java/freemarker/core/TemplateMarkupOutputModel.java |  4 ++--
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/main/java/freemarker/core/CommonMarkupOutputFormat.java b/src/main/java/freemarker/core/CommonMarkupOutputFormat.java
index c9200bf8..ff1fe788 100644
--- a/src/main/java/freemarker/core/CommonMarkupOutputFormat.java
+++ b/src/main/java/freemarker/core/CommonMarkupOutputFormat.java
@@ -117,6 +117,16 @@ public abstract class CommonMarkupOutputFormat<MO extends CommonTemplateMarkupOu
 
     /**
      * Creates a new {@link CommonTemplateMarkupOutputModel} that's bound to this {@link OutputFormat} instance.
+     * When this is called from {@link CommonMarkupOutputFormat}, exactly one of the parameters will be
+     * non-{@code null}.
+     *
+     * @param plainTextContent
+     *      {@code null} if the content is markup that possibly can be described as plain text without loss.
+     * @param markupContent
+     *      Typically will be {@code null} if {@code plainTextContent} is not {@code null}. While the plain text always
+     *      can be converted to markup via {@link #escapePlainText(String)}, it's up to the implementation if it wants
+     *      to do that now and store the markup, or later on demand (like each time when
+     *      {@link #getMarkupString(CommonTemplateMarkupOutputModel)} is called).
      */
     protected abstract MO newTemplateMarkupOutputModel(String plainTextContent, String markupContent)
             throws TemplateModelException;
diff --git a/src/main/java/freemarker/core/MarkupOutputFormat.java b/src/main/java/freemarker/core/MarkupOutputFormat.java
index 81ffe8b2..e8b3d969 100644
--- a/src/main/java/freemarker/core/MarkupOutputFormat.java
+++ b/src/main/java/freemarker/core/MarkupOutputFormat.java
@@ -26,8 +26,8 @@ import freemarker.template.TemplateModelException;
 
 /**
  * Superclass of {@link OutputFormat}-s that represent a "markup" format, which is any format where certain character
- * sequences have special meaning and thus may need escaping. (Escaping is important for FreeMarker, as typically it has
- * to insert non-markup text from the data-model into the output markup. See also:
+ * sequences have special meaning, and thus may need escaping. (Escaping is important for FreeMarker, as typically it
+ * has to insert non-markup text from the data-model into the output markup. See also:
  * {@link Configuration#setOutputFormat(OutputFormat)}.)
  * 
  * <p>
@@ -77,7 +77,7 @@ public abstract class MarkupOutputFormat<MO extends TemplateMarkupOutputModel> e
 
     /**
      * Equivalent to calling {@link #fromPlainTextByEscaping(String)} and then
-     * {@link #output(TemplateMarkupOutputModel, Writer)}, but the implementation may uses a more efficient solution.
+     * {@link #output(TemplateMarkupOutputModel, Writer)}, but the implementation may use a more efficient solution.
      */
     public abstract void output(String textToEsc, Writer out) throws IOException, TemplateModelException;
     
@@ -105,7 +105,7 @@ public abstract class MarkupOutputFormat<MO extends TemplateMarkupOutputModel> e
     
     /**
      * Should give the same result as {@link #fromPlainTextByEscaping(String)} and then
-     * {@link #getMarkupString(TemplateMarkupOutputModel)}, but the implementation may uses a more efficient solution.
+     * {@link #getMarkupString(TemplateMarkupOutputModel)}, but the implementation may use a more efficient solution.
      */
     public abstract String escapePlainText(String plainTextContent) throws TemplateModelException;
 
diff --git a/src/main/java/freemarker/core/TemplateMarkupOutputModel.java b/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
index 7043fba2..19a02ad8 100644
--- a/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
+++ b/src/main/java/freemarker/core/TemplateMarkupOutputModel.java
@@ -27,8 +27,8 @@ import freemarker.template.TemplateScalarModel;
  * mechanism. Values of this kind are exempt from {@link OutputFormat}-based automatic escaping.
  * 
  * <p>
- * Each implementation of this type has a {@link OutputFormat} subclass pair, whose singleton instance is returned by
- * {@link #getOutputFormat()}. See more about how markup output values work at {@link OutputFormat}.
+ * Each implementation of this type has a corresponding {@link OutputFormat} subclass, whose singleton instance is
+ * returned by {@link #getOutputFormat()}. See more about how markup output values work at {@link OutputFormat}.
  * 
  * <p>
  * Note that {@link TemplateMarkupOutputModel}-s are by design not treated like {@link TemplateScalarModel}-s, and so