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 <[email protected]> Authored: Fri Jun 23 21:06:16 2017 +0200 Committer: ddekany <[email protected]> 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;
