[2/2] incubator-freemarker git commit: (TemplateScalarModel JavaDoc improvement)

[dd...@apache.org]

(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 <dd...@apache.org>
Authored: Sun Aug 20 23:57:08 2017 +0200
Committer: ddekany <dd...@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;