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
Commit: 4b5b7e8715359effbc39990c01305b9703abf90f
Parents: 367560f
Author: ddekany <ddek...@apache.org>
Authored: Fri Jun 23 21:06:16 2017 +0200
Committer: ddekany <ddek...@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;

Reply via email to