Mailing-List: contact notifications-help@freemarker.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@freemarker.incubator.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: ddekany@apache.org
To: notifications@freemarker.incubator.apache.org
Message-Id: <4b400a4dc2034a0982f946de3490f812@git.apache.org>
Subject: incubator-freemarker git commit: TemplateHashModelEx2 JavaDoc
Date: Mon, 30 May 2016 22:10:24 +0000 (UTC)
archived-at: Mon, 30 May 2016 22:10:29 -0000

Repository: incubator-freemarker
Updated Branches:
  refs/heads/2.3-gae 59f7d4667 -> 7e08ebc1d


TemplateHashModelEx2 JavaDoc


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

Branch: refs/heads/2.3-gae
Commit: 7e08ebc1dc8ee049cdbe0c0c08675ea84a292f87
Parents: 59f7d46
Author: ddekany <ddekany@apache.org>
Authored: Tue May 31 00:10:17 2016 +0200
Committer: ddekany <ddekany@apache.org>
Committed: Tue May 31 00:10:17 2016 +0200

----------------------------------------------------------------------
 .../template/TemplateHashModelEx2.java          | 43 ++++++++++++++++++--
 1 file changed, 40 insertions(+), 3 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/7e08ebc1/src/main/java/freemarker/template/TemplateHashModelEx2.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/TemplateHashModelEx2.java b/src/main/java/freemarker/template/TemplateHashModelEx2.java
index 9e7a8d7..11be6cd 100644
--- a/src/main/java/freemarker/template/TemplateHashModelEx2.java
+++ b/src/main/java/freemarker/template/TemplateHashModelEx2.java
@@ -18,25 +18,62 @@
  */
 package freemarker.template;
 
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
 /**
  * Adds key-value pair listing capability to {@link TemplateHashModelEx}. While in many cases that can also be achieved
  * with {@link #keys()} and then {@link #get(String)}, that has some problems. One is that {@link #get(String)} only
- * accepts string keys, while {@link #keys()} can return non-string keys too. The other is that {@link #keys()} and then
- * {@link #get(String)} for each key can be slower than listing the key-value pairs in one go.
+ * accepts string keys, while {@link #keys()} can return non-string keys too. The other is that calling {@link #keys()}
+ * and then {@link #get(String)} for each key can be slower than listing the key-value pairs in one go.
  * 
- * @since 2.3.25 
+ * @since 2.3.25
  */
 public interface TemplateHashModelEx2 extends TemplateHashModelEx {
 
+    /**
+     * @return The iterator that walks through the key-value pairs in the hash. Not {@code null}. 
+     */
     KeyValuePairIterator keyValuePairIterator();
     
+    /**
+     * A key-value pair in a hash; used for {@link KeyValuePairIterator}.
+     *  
+     * @since 2.3.25
+     */
     interface KeyValuePair {
+        
+        /**
+         * @return Any type of {@link TemplateModel}, maybe {@code null} (if the hash entry key is {@code null}).
+         */
         TemplateModel getKey() throws TemplateModelException;
+        
+        /**
+         * @return Any type of {@link TemplateModel}, maybe {@code null} (if the hash entry value is {@code null}).
+         */
         TemplateModel getValue() throws TemplateModelException;
     }
     
+    /**
+     * Iterates over the key-value pairs in a hash. This is very similar to an {@link Iterator}, but has a fixed item
+     * type, can throw {@link TemplateModelException}-s, and has no {@code remove()} method. 
+     *
+     * @since 2.3.25
+     */
     interface KeyValuePairIterator {
+        
+        /**
+         * Similar to {@link Iterator#hasNext()}.
+         */
         boolean hasNext() throws TemplateModelException;
+        
+        /**
+         * Similar to {@link Iterator#next()}.
+         * 
+         * @return Not {@code null}
+         * 
+         * @throws NoSuchElementException
+         */
         KeyValuePair next() throws TemplateModelException;
     }