(freemarker) 02/02: (Minor javadoc content improvement)

[dd...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ddekany pushed a commit to branch 2.3-gae
in repository https://gitbox.apache.org/repos/asf/freemarker.git

commit d88154f9b8c86575b838eb77f0f94fd14d7f6e6d
Author: ddekany <dd...@apache.org>
AuthorDate: Sun Dec 10 15:57:48 2023 +0100

    (Minor javadoc content improvement)
---
 src/main/java/freemarker/core/Environment.java  |  8 ++++++++
 src/main/java/freemarker/template/Template.java | 11 ++++++-----
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/main/java/freemarker/core/Environment.java b/src/main/java/freemarker/core/Environment.java
index 65563de1..bb435714 100644
--- a/src/main/java/freemarker/core/Environment.java
+++ b/src/main/java/freemarker/core/Environment.java
@@ -202,6 +202,14 @@ public final class Environment extends Configurable {
         threadEnv.set(env);
     }
 
+    /**
+     * Creates an environment with the given main (top-level) template that it intends to {@linkplain #process()} later;
+     * typically, it's better to use {@link Template#createProcessingEnvironment(Object, Writer)} instead of this.
+     *
+     * @param template Not {@code null}
+     * @param rootDataModel Not {@code null}
+     * @param out Not {@code null}
+     */
     public Environment(Template template, final TemplateHashModel rootDataModel, Writer out) {
         super(template);
         configuration = template.getConfiguration();
diff --git a/src/main/java/freemarker/template/Template.java b/src/main/java/freemarker/template/Template.java
index 595b6d8d..967d222f 100644
--- a/src/main/java/freemarker/template/Template.java
+++ b/src/main/java/freemarker/template/Template.java
@@ -413,11 +413,12 @@ public class Template extends Configurable {
     }
     
    /**
-    * Creates a {@link freemarker.core.Environment Environment} object, using this template, the data-model provided as
-    * parameter. You have to call {@link Environment#process()} on the return value to set off the actual rendering.
+    * Creates a {@link freemarker.core.Environment Environment} object, with this template as the main (top-level
+    * template), and the data-model provided as parameter. You have to call {@link Environment#process()} on the return
+    * value to start actual template processing (that is, to run the template, to generate output).
     * 
     * <p>Use this method if you want to do some special initialization on the {@link Environment} before template
-    * processing, or if you want to read the {@link Environment} after template processing. Otherwise using
+    * processing, or if you want to read the {@link Environment} after template processing. Otherwise, using
     * {@link Template#process(Object, Writer)} is simpler.
     *
     * <p>Example:
@@ -445,12 +446,12 @@ public class Template extends Configurable {
     * TemplateModel x = env.getVariable("x");  // read back a variable set by the template</pre>
     *
     * @param dataModel the holder of the variables visible from all templates; see {@link #process(Object, Writer)} for
-    *     more details.
+    *     more details. If {@code null}, the data model will be empty.
     * @param wrapper The {@link ObjectWrapper} to use to wrap objects into {@link TemplateModel}
     *     instances. Normally you left it {@code null}, in which case {@link Configurable#getObjectWrapper()} will be
     *     used.
     * @param out The {@link Writer} where the output of the template will go; see {@link #process(Object, Writer)} for
-    *     more details.
+    *     more details. Can't be {@code null}.
     *     
     * @return the {@link Environment} object created for processing. Call {@link Environment#process()} to process the
     *    template.