freemarker-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ddek...@apache.org
Subject [3/3] incubator-freemarker git commit: Minor JavaDoc improvements
Date Fri, 23 Jun 2017 19:06:39 GMT
Minor JavaDoc improvements


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/4b5b7e87
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/4b5b7e87
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/4b5b7e87

Branch: refs/heads/2.3-gae
Commit: 4b5b7e8715359effbc39990c01305b9703abf90f
Parents: 367560f
Author: ddekany <ddekany@apache.org>
Authored: Fri Jun 23 21:06:16 2017 +0200
Committer: ddekany <ddekany@apache.org>
Committed: Fri Jun 23 21:06:16 2017 +0200

----------------------------------------------------------------------
 src/main/java/freemarker/core/IfBlock.java           |  2 +-
 src/main/java/freemarker/core/TemplateElement.java   | 11 ++++++-----
 src/main/java/freemarker/core/TemplateObject.java    |  3 ---
 src/main/java/freemarker/ext/beans/BeansWrapper.java |  2 +-
 src/main/java/freemarker/template/Configuration.java | 10 ++++++++--
 src/main/java/freemarker/template/Template.java      |  5 ++++-
 6 files changed, 20 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4b5b7e87/src/main/java/freemarker/core/IfBlock.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/IfBlock.java b/src/main/java/freemarker/core/IfBlock.java
index f61e2d3..223d755 100644
--- a/src/main/java/freemarker/core/IfBlock.java
+++ b/src/main/java/freemarker/core/IfBlock.java
@@ -25,7 +25,7 @@ import freemarker.template.TemplateException;
 
 /**
  * Container for a group of related #if, #elseif and #else elements.
- * Each such block is a nested {@link ConditionalBlock}. Note that if an #if has no #else
of #elseif,
+ * Each such block is a nested {@link ConditionalBlock}. Note that if an #if has no #else
or #elseif,
  * {@link ConditionalBlock} doesn't need this parent element. 
  */
 final class IfBlock extends TemplateElement {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4b5b7e87/src/main/java/freemarker/core/TemplateElement.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateElement.java b/src/main/java/freemarker/core/TemplateElement.java
index f63db63..a8dedea 100644
--- a/src/main/java/freemarker/core/TemplateElement.java
+++ b/src/main/java/freemarker/core/TemplateElement.java
@@ -77,11 +77,12 @@ abstract public class TemplateElement extends TemplateObject {
     abstract TemplateElement[] accept(Environment env) throws TemplateException, IOException;
 
     /**
-     * One-line description of the element, that contain all the information that is used
in {@link #getCanonicalForm()}
-     * , except the nested content (elements) of the element. The expressions inside the
element (the parameters) has to
-     * be shown. Meant to be used for stack traces, also for tree views that don't go down
to the expression-level.
-     * There are no backward-compatibility guarantees regarding the format used ATM, but
it must be regular enough to be
-     * machine-parseable, and it must contain all information necessary for restoring an
AST equivalent to the original.
+     * One-line description of the element, that contains all the information that is used
in
+     * {@link #getCanonicalForm()}, except the nested content (elements) of the element.
The expressions inside the
+     * element (the parameters) has to be shown. Meant to be used for stack traces, also
for tree views that don't go
+     * down to the expression-level. There are no backward-compatibility guarantees regarding
the format used ATM, but
+     * it must be regular enough to be machine-parseable, and it must contain all information
necessary for restoring an
+     * AST equivalent to the original.
      * 
      * This final implementation calls {@link #dump(boolean) dump(false)}.
      * 

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4b5b7e87/src/main/java/freemarker/core/TemplateObject.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateObject.java b/src/main/java/freemarker/core/TemplateObject.java
index 87ee274..248395d 100644
--- a/src/main/java/freemarker/core/TemplateObject.java
+++ b/src/main/java/freemarker/core/TemplateObject.java
@@ -198,9 +198,6 @@ public abstract class TemplateObject {
      * that is equivalent with the original could be reconstructed from the tree view. Thus,
for literal values that are
      * leaf nodes the symbols should be the canonical form of value.
      * 
-     * Note that {@link TemplateElement#getDescription()} has similar role, only it doesn't
go under the element level
-     * (i.e. down to the expression level), instead it always prints the embedded expressions
itself.
-     * 
      * @see #getCanonicalForm()
      * @see TemplateElement#getDescription()
      */

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4b5b7e87/src/main/java/freemarker/ext/beans/BeansWrapper.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/ext/beans/BeansWrapper.java b/src/main/java/freemarker/ext/beans/BeansWrapper.java
index 93cdcb6..1a10bf0 100644
--- a/src/main/java/freemarker/ext/beans/BeansWrapper.java
+++ b/src/main/java/freemarker/ext/beans/BeansWrapper.java
@@ -1516,7 +1516,7 @@ public class BeansWrapper implements RichObjectWrapper, WriteProtectable
{
      * enumeration. To obtain an enum model for a class, get the element of this
      * hash with the fully qualified class name. For example, if you place this 
      * hash model inside the root data model under name "enums", you can use 
-     * i.e. <code>statics["java.math.RoundingMode"].UP</code> to access the 
+     * i.e. <code>enums["java.math.RoundingMode"].UP</code> to access the 
      * {@link java.math.RoundingMode#UP} value.
      * @return a hash model whose keys are fully qualified class names, and
      * that returns hash models whose elements are the enum models of the

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4b5b7e87/src/main/java/freemarker/template/Configuration.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java
index a2df266..42426e8 100644
--- a/src/main/java/freemarker/template/Configuration.java
+++ b/src/main/java/freemarker/template/Configuration.java
@@ -122,7 +122,7 @@ import freemarker.template.utility.XmlEscape;
  *  ...
  *  
  *  // Later, whenever the application needs a template (so you may do this a lot, and from
multiple threads):
- *  {@link Template Template} myTemplate = cfg.{@link #getTemplate(String) getTemplate}("myTemplate.html");
+ *  {@link Template Template} myTemplate = cfg.{@link #getTemplate(String) getTemplate}("myTemplate.ftlh");
  *  myTemplate.{@link Template#process(Object, java.io.Writer) process}(dataModel, out);</pre>
  * 
  * <p>A couple of settings that you should not leave on its default value are:
@@ -2324,7 +2324,9 @@ public class Configuration extends Configurable implements Cloneable,
ParserConf
      * messages (or the column number you get through other API-s). So for example if the
users edit templates in an
      * editor where the tab width is set to 4, you should set this to 4 so that the column
numbers printed by FreeMarker
      * will match the column number shown in the editor. This setting doesn't affect the
output of templates, as a tab
-     * in the template will remain a tab in the output too.
+     * in the template will remain a tab in the output too. If you set this setting to 1,
then tab characters will be
+     * kept in the return value of {@link Template#getSource(int, int, int, int)}, otherwise
they will be replaced with
+     * the appropriate number of spaces.
      * 
      * @param tabSize
      *            At least 1, at most 256.
@@ -2651,12 +2653,16 @@ public class Configuration extends Configurable implements Cloneable,
ParserConf
      * default encoding if no encoding is set explicitly for the specified
      * locale. You can associate encodings with locales using 
      * {@link #setEncoding(Locale, String)} or {@link #loadBuiltInEncodingMap()}.
+     * 
+     * @param locale Shouldn't be {@code null}, though for backward compatibility it's accepted
when the locale to
+     *               encoding {@link Map} (see earlier) is empty.
      */
     public String getEncoding(Locale locale) {
         if (localeToCharsetMap.isEmpty()) {
             return defaultEncoding;
         } else {
             // Try for a full name match (may include country and variant)
+            NullArgumentException.check("locale", locale);
             String charset = (String) localeToCharsetMap.get(locale.toString());
             if (charset == null) {
                 if (locale.getVariant().length() > 0) {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/4b5b7e87/src/main/java/freemarker/template/Template.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Template.java b/src/main/java/freemarker/template/Template.java
index 26aa071..6c2aa4e 100644
--- a/src/main/java/freemarker/template/Template.java
+++ b/src/main/java/freemarker/template/Template.java
@@ -33,6 +33,7 @@ import java.util.Collections;
 import java.util.Enumeration;
 import java.util.HashMap;
 import java.util.List;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Vector;
 
@@ -598,7 +599,9 @@ public class Template extends Configurable {
     }
 
     /**
-     * Returns the default character encoding used for reading included files.
+     * The encoding that was (allegedly) used to read this template; also the the default
character encoding used for
+     * reading files included from this template. Possibly {@code null}, in which case you
are supposed to use
+     * {@link Configuration#getEncoding(Locale)}. 
      */
     public String getEncoding() {
         return this.encoding;


Mime
View raw message