(TemplateScalarModel JavaDoc improvement)
Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/05dc3856 Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/05dc3856 Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/05dc3856 Branch: refs/heads/2.3-gae Commit: 05dc3856ce729946b9cf60c17b5e0a1331a4d77c Parents: 61902c3 Author: ddekany <ddek...@apache.org> Authored: Sun Aug 20 23:57:08 2017 +0200 Committer: ddekany <ddek...@apache.org> Committed: Sun Aug 20 23:57:08 2017 +0200 ---------------------------------------------------------------------- .../java/freemarker/template/TemplateScalarModel.java | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/05dc3856/src/main/java/freemarker/template/TemplateScalarModel.java ---------------------------------------------------------------------- diff --git a/src/main/java/freemarker/template/TemplateScalarModel.java b/src/main/java/freemarker/template/TemplateScalarModel.java index ca67f75..7b628de 100644 --- a/src/main/java/freemarker/template/TemplateScalarModel.java +++ b/src/main/java/freemarker/template/TemplateScalarModel.java @@ -19,10 +19,15 @@ package freemarker.template; +import freemarker.core.TemplateMarkupOutputModel; + /** * "string" template language data-type; like in Java, an unmodifiable UNICODE character sequence. * (The name of this interface should be {@code TemplateStringModel}. The misnomer is inherited from the * old times, when this was the only single-value type in FreeMarker.) + * When a template has to print a value of this class, it will assume that it stores plain text (not HTML, XML, etc.), + * and thus it will be possibly auto-escaped. To avoid that, use the appropriate {@link TemplateMarkupOutputModel} + * instead. */ public interface TemplateScalarModel extends TemplateModel { @@ -32,12 +37,9 @@ public interface TemplateScalarModel extends TemplateModel { public TemplateModel EMPTY_STRING = new SimpleScalar(""); /** - * Returns the string representation of this model. Don't return {@code null}, as that will cause exception. (In - * classic-compatible mode the engine will convert {@code null} into empty string, though.) - * - * <p> - * Objects of this type should be immutable, that is, calling {@link #getAsString()} should always return the same - * value as for the first time. + * Returns the {@link String} representation of this model. Returning {@code null} is illegal, and may cause + * exception in the calling code. (Except, in classic-compatible mode the engine will convert {@code null} into + * empty string.) */ public String getAsString() throws TemplateModelException;