[28/50] incubator-freemarker git commit: FREEMARKER-60: Document interaction between lazy import and #global

[dd...@apache.org]

FREEMARKER-60: Document interaction between lazy import and #global


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

Branch: refs/heads/2.3
Commit: 96d3971cc6f21974729f4fc0a7dec159b5a4ff42
Parents: 5d81db7
Author: ddekany <dd...@apache.org>
Authored: Tue Jul 4 21:05:06 2017 +0200
Committer: ddekany <dd...@apache.org>
Committed: Tue Jul 4 21:05:06 2017 +0200

----------------------------------------------------------------------
 src/main/java/freemarker/core/Configurable.java | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/96d3971c/src/main/java/freemarker/core/Configurable.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java
index 4887dfe..492282a 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -1703,16 +1703,20 @@ public class Configurable {
     /**
      * Specifies if {@code <#import ...>} (and {@link Environment#importLib(String, String)}) should delay the loading
      * and processing of the imported templates until the content of the imported namespace is actually accessed. This
-     * makes the overhead of <em>unused</em> imports negligible. A drawback is that importing a missing or otherwise
-     * broken template will be successful, and the problem will remain hidden until (and if) the namespace content is
-     * actually used. Also, you lose the strict control over when the namespace initializing code in the imported
-     * template will be executed, though it shouldn't mater for well written imported templates anyway. Note that the
-     * namespace initializing code will run with the same {@linkplain Configurable#getLocale() locale} as it was at the
-     * point of the {@code <#import ...>} call (other settings won't be handled specially like that).
+     * makes the overhead of <em>unused</em> imports negligible. Note that turning on lazy importing isn't entirely
+     * transparent, as accessing global variables (usually created with {@code <#global ...=...>}) that should be
+     * created by the imported template won't trigger the loading and processing of the lazily imported template
+     * (because globals aren't accessed through the namespace variable), so the global variable will just be missing.
+     * In general, you lose the strict control over when the namespace initializing code in the imported template will
+     * be executed, though it shouldn't mater for most well designed imported templates.
+     * Another drawback is that importing a missing or otherwise broken template will be successful, and the problem
+     * will remain hidden until (and if) the namespace content is actually used. Note that the namespace initializing
+     * code will run with the same {@linkplain Configurable#getLocale() locale} as it was at the point of the
+     * {@code <#import ...>} call (other settings won't be handled specially like that).
      * 
      * <p>
      * The default is {@code false} (and thus imports are eager) for backward compatibility, which can cause
-     * perceivable overhead if you have many imports and only a few of them is used.
+     * perceivable overhead if you have many imports and only a few of them is actually used.
      * 
      * <p>
      * This setting also affects {@linkplain #setAutoImports(Map) auto-imports}, unless you have set a non-{@code null}