1 files changed, 166 insertions, 5 deletions
diff --git a/java/src/Freeze/NavigableMap.java b/java/src/Freeze/NavigableMap.java
index 7d9e3ecfbc8..42e8960453d 100644
--- a/java/src/Freeze/NavigableMap.java
+++ b/java/src/Freeze/NavigableMap.java
@@ -9,34 +9,195 @@
 
 package Freeze;
 
+/**
+ * Parent interface for Freeze maps.
+ **/
 public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
 {
-    //
-    // Faster alternative to the standard remove() method because it
-    // doesn't read and decode the old value.
-    //
+    /**
+     * Alternative to <code>java.util.SortedMap.remove</code>. This version
+     * is more efficient because it does not decode and return the
+     * old value.
+     *
+     * @param key The key of the entry to remove.
+     * @return <code>true</code> if an entry for <code>key</code> was removed;
+     * <code>false</code>, otherwise.
+     **/
     boolean fastRemove(K key);
 
+    /**
+     * Returns The entry with the least key.
+     *
+     * @return The entry with the least key, or <code>null</code> if the map is empty.
+     **/
     java.util.Map.Entry<K, V> firstEntry();
+
+    /**
+     * Returns The entry with the greatest key.
+     *
+     * @return The entry with the greatest key, or <code>null</code> if the map is empty.
+     **/
     java.util.Map.Entry<K, V> lastEntry();
 
+    /**
+     * Returns the entry with the least key greater than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The entry with the least key greater than or equal to the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> ceilingEntry(K key);
+
+    /**
+     * Returns the entry with the greatest key less than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The entry with the greatest key less than or equal to the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> floorEntry(K key);
+
+    /**
+     * Returns the entry with the least key strictly greater than the given key.
+     *
+     * @param key The key.
+     * @return The entry with the least key strictly greater than the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> higherEntry(K key);
+
+    /**
+     * Returns the entry with the greatest key strictly less than the given key.
+     *
+     * @param key The key.
+     * @return The entry with the greatest key strictly less than the given key,
+     * or <code>null</code> if there is no such entry.
+     **/
     java.util.Map.Entry<K, V> lowerEntry(K key);
 
+    /**
+     * Returns the least key greater than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The least key greater than or equal to the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K ceilingKey(K key);
+
+    /**
+     * Returns the greatest key less than or equal to the given key.
+     *
+     * @param key The key.
+     * @return The greatest key less than or equal to the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K floorKey(K key);
+
+    /**
+     * Returns the least key strictly greater than the given key.
+     *
+     * @return The least key strictly greater than the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K higherKey(K key);
+
+    /**
+     * Returns the greatest key strictly less than the given key.
+     *
+     * @return The greatest key strictly less than the given key,
+     * or <code>null</code> if there is no such key.
+     **/
     K lowerKey(K key);
 
+    /**
+     * Returns a reverse order <code>Set</code> view of the keys contained in this map. The set's iterator
+     * returns the keys in descending order. The set is backed by the map, so changes to the map are reflected
+     * in the set, and vice-versa. If the map is modified while an iteration over the set is in progress
+     * (except through the iterator's own <code>remove</code> or <code>fastRemove</code> operation), the results
+     * of the iteration are undefined.
+     *
+     * @return A reverse order set view of the keys in this map.
+     **/
     java.util.Set<K> descendingKeySet();
+
+    /**
+     * Returns a reverse order view of the mappings contained in this map.
+     * The descending map is backed by this map, so changes to the map are reflected in the descending map,
+     * and vice-versa. If either map is modified while an iteration over a collection view of either map is
+     * in progress (except through the iterator's own <code>remove</code> or <code>fastRemove</code>operation),
+     * the results of the iteration are undefined. 
+     *
+     * @return a Reverse order view of this map.
+     **/
     NavigableMap<K, V> descendingMap();
 
+    /**
+     * Returns a view of the portion of this map whose keys are strictly less than <code>toKey</code>, or less than
+     * or equal to <code>toKey</code> if <code>inclusive</code> is true.
+     * The returned map is backed by this map, so changes in the returned map are reflected in this map,
+     * and vice-versa. The returned map supports all optional map operations that this map supports. 
+     * <p>
+     * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
+     * outside its range.
+     *
+     * @param toKey High endpoint of the keys in the returned map.
+     * @param inclusive If <code>true</code>, the endpoint is included in the returned map; otherwise, the endpoint
+     * is excluded.
+     * @return A view of the portion of this map whose keys are strictly less than <code>toKey</code>, or
+     * less than or equal to <code>toKey</code> if <code>inclusive</code> is true.
+     **/
     NavigableMap<K, V> headMap(K toKey, boolean inclusive);
-    NavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
+
+    /**
+     * Returns a view of the portion of this map whose keys are strictly greater than <code>fromKey</code>, or greater
+     * than or equal to <code>fromKey</code> if <code>inclusive</code> is true.
+     * The returned map is backed by this map, so changes in the returned map are reflected in this map,
+     * and vice-versa. The returned map supports all optional map operations that this map supports. 
+     * <p>
+     * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
+     * outside its range.
+     *
+     * @param fromKey Low endpoint of the keys in the returned map.
+     * @param inclusive If <code>true</code>, the endpoint is included in the returned map; otherwise, the endpoint
+     * is excluded.
+     * @return A view of the portion of this map whose keys are strictly greater than <code>fromKey</code>, or
+     * greater than or equal to <code>fromKey</code> if <code>inclusive</code> is true.
+     **/
     NavigableMap<K, V> tailMap(K fromKey, boolean inclusive);
 
+    /**
+     * Returns a view of the portion of this map whose keys range from <code>fromKey</code> to <code>toKey</code>.
+     * If <code>fromKey</code> and <code>toKey</code> are equal, the returned map is empty unless
+     * <code>fromExclusive</code> and <code>toExclusive</code> are both <code>true</code>.
+     * The returned map is backed by this map, so changes in the returned map are reflected in this map, and
+     * vice-versa. The returned map supports all optional map operations that this map supports. 
+     * <p>
+     * The returned map throws an <code>IllegalArgumentException</code> on an attempt to insert a key
+     * outside its range, or to construct a submap either of whose endpoints lie outside its range.
+     *
+     * @param fromKey Low endpoint of the keys in the returned map.
+     * @param fromInclusive <code>true</code> if the low endpoint is to be included in the returned view;
+     * <code>false, otherwise</code>.
+     * @param toKey High endpoint of the keys in the returned map.
+     * @param toInclusive <code>true</code> if the high endpoint is to be included in the returned view;
+     * <code>false, otherwise</code>.
+     * @return A view of the portion of this map whose keys range from <code>fromKey</code> to <code>toKey</code>.
+     **/
+    NavigableMap<K, V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive);
+
+    /**
+     * Removes and returns a key-value mapping associated with the least key in this map,
+     * or <code>null</code> if the map is empty.
+     *
+     * @return The removed first entry, or <code>null</code> if this map is empty.
+     **/
     java.util.Map.Entry<K, V> pollFirstEntry();
+
+    /**
+     * Removes and returns a key-value mapping associated with the greatest key in this map,
+     * or <code>null</code> if the map is empty.
+     *
+     * @return The removed last entry, or <code>null</code> if this map is empty.
+     **/
     java.util.Map.Entry<K, V> pollLastEntry();
 }