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 <[email protected]> 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
