bug 4669 - javadoc for Freeze

4 files changed, 370 insertions, 22 deletions

diff --git a/cpp/src/slice2freezej/Main.cpp b/cpp/src/slice2freezej/Main.cpp
index 7e630a5b14d..3341b03fe89 100644
--- a/cpp/src/slice2freezej/Main.cpp
+++ b/cpp/src/slice2freezej/Main.cpp
@@ -439,13 +439,29 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
 
     if(dict.indices.size() > 0)
     {
-        out << sp << nl << "public static class IndexComparators";
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Supplies a comparator for each index key."
+            << nl << " */";
+        out << nl << "public static class IndexComparators";
         out << sb;
-        out << sp << nl << "public" << nl << "IndexComparators()";
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Default constructor assigns null to the comparator for each index key."
+            << nl << " */";
+        out << nl << "public" << nl << "IndexComparators()";
         out << sb;
         out << eb;
 
-        out << sp << nl << "public" << nl << "IndexComparators(";
+        out << sp;
+        out << nl << "/**"
+            << nl << " * This constructor accepts a comparator for each index key.";
+        for(i = 0; i < dict.indices.size(); ++i)
+        {
+            out << nl << " * @param " << members[i] << "Comparator Comparator for <code>" << members[i] << "</code>.";
+        }
+        out << nl << " */";
+        out << nl << "public" << nl << "IndexComparators(";
         for(i = 0; i < dict.indices.size(); ++i)
         {
             if(i > 0)
@@ -466,6 +482,7 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
         out << sp;
         for(i = 0; i < dict.indices.size(); ++i)
         {
+            out << nl << "/** Comparator for <code>" << members[i] << "</code>. */";
             out << nl << "public java.util.Comparator<" << typeToObjectString(indexTypes[i]) << "> " << members[i]
                 << "Comparator;";
         }
@@ -500,7 +517,25 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
 
     if(dict.indices.size() > 0)
     {
-        out << sp << nl << "public" << nl << name
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Instantiates a Freeze map using the given connection. If the database"
+            << nl << " * named in <code>__dbName</code> does not exist and <code>__createDb</code>"
+            << nl << " * is true, the database is created automatically, otherwise this constructor"
+            << nl << " * raises <code>DatabaseException</code>."
+            << nl << " * @param __connection The Freeze connection associated with this map."
+            << nl << " * @param __dbName The name of the Berkeley DB database."
+            << nl << " * @param __createDb True if the database should be created if it does not"
+            << nl << " *   already exist, false otherwise."
+            << nl << " * @param __comparator A comparator for the map's main key, or null to use the"
+            << nl << " *   default key comparison strategy."
+            << nl << " * @param __indexComparators A map of string to comparator, representing the"
+            << nl << " *   key comparator for each of the map's indices. The map uses the default"
+            << nl << " *   key comparison strategy for an index if <code>__indexComparators</code>"
+            << nl << " *   is null, or if no entry can be found in the comparators map for an index."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */"
+            << nl << "public" << nl << name
             << "(Freeze.Connection __connection, String __dbName, boolean __createDb, "
             << "java.util.Comparator<" << keyTypeS  << "> __comparator, "
             << "IndexComparators __indexComparators)";
@@ -511,7 +546,21 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
         out << eb;
     }
 
-    out << sp << nl << "public" << nl << name
+    out << sp;
+    out << nl << "/**"
+        << nl << " * Instantiates a Freeze map using the given connection. If the database"
+        << nl << " * named in <code>__dbName</code> does not exist and <code>__createDb</code>"
+        << nl << " * is true, the database is created automatically, otherwise this constructor"
+        << nl << " * raises <code>DatabaseException</code>."
+        << nl << " * @param __connection The Freeze connection associated with this map."
+        << nl << " * @param __dbName The name of the Berkeley DB database."
+        << nl << " * @param __createDb True if the database should be created if it does not"
+        << nl << " *   already exist, false otherwise."
+        << nl << " * @param __comparator A comparator for the map's main key, or null to use the"
+        << nl << " *   default key comparison strategy."
+        << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+        << nl << " */";
+    out << nl << "public" << nl << name
         << "(Freeze.Connection __connection, String __dbName, boolean __createDb, "
         << "java.util.Comparator<" << keyTypeS << "> __comparator)";
     out << sb;
@@ -526,13 +575,35 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
     }
     out << eb;
 
-    out << sp << nl << "public" << nl << name
+    out << sp;
+    out << nl << "/**"
+        << nl << " * Instantiates a Freeze map using the given connection. If the database"
+        << nl << " * named in <code>__dbName</code> does not exist and <code>__createDb</code>"
+        << nl << " * is true, the database is created automatically, otherwise this constructor"
+        << nl << " * raises <code>DatabaseException</code>. The map uses the default key"
+        << nl << " * comparison strategy."
+        << nl << " * @param __connection The Freeze connection associated with this map."
+        << nl << " * @param __dbName The name of the Berkeley DB database."
+        << nl << " * @param __createDb True if the database should be created if it does not"
+        << nl << " *   already exist, false otherwise."
+        << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+        << nl << " */";
+    out << nl << "public" << nl << name
         << "(Freeze.Connection __connection, String __dbName, boolean __createDb)";
     out << sb;
     out << nl << "this(__connection, __dbName, __createDb, null);";
     out << eb;
 
-    out << sp << nl << "public" << nl << name << "(Freeze.Connection __connection, String __dbName)";
+    out << sp;
+    out << nl << "/**"
+        << nl << " * Instantiates a Freeze map using the given connection. If the database"
+        << nl << " * named in <code>__dbName</code> does not exist, it is created automatically."
+        << nl << " * The map uses the default key comparison strategy."
+        << nl << " * @param __connection The Freeze connection associated with this map."
+        << nl << " * @param __dbName The name of the Berkeley DB database."
+        << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+        << nl << " */";
+    out << nl << "public" << nl << name << "(Freeze.Connection __connection, String __dbName)";
     out << sb;
     out << nl << "this(__connection, __dbName, true);";
     out << eb;
@@ -542,7 +613,22 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
     //
     if(dict.indices.size() > 0)
     {
-        out << sp << nl << "public static void" << nl
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Copies an existing database. The new database has the name given in"
+            << nl << " * <code>__dbName</code>, and the old database is renamed with a UUID"
+            << nl << " * suffix."
+            << nl << " * @param __connection The Freeze connection associated with this map."
+            << nl << " * @param __dbName The name of the Berkeley DB database."
+            << nl << " * @param __comparator A comparator for the map's main key, or null to use the"
+            << nl << " *   default key comparison strategy."
+            << nl << " * @param __indexComparators A map of string to comparator, representing the"
+            << nl << " *   key comparator for each of the map's indices. The map uses the default"
+            << nl << " *   key comparison strategy for an index if <code>__indexComparators</code>"
+            << nl << " *   is null, or if no entry can be found in the comparators map for an index."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public static void" << nl
             << "recreate(Freeze.Connection __connection, String __dbName, "
             << "java.util.Comparator<" << keyTypeS  << "> __comparator, "
             << "IndexComparators __indexComparators)";
@@ -554,7 +640,18 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
         out << eb;
     }
 
-    out << sp << nl << "public static void" << nl
+    out << sp;
+    out << nl << "/**"
+        << nl << " * Copies an existing database. The new database has the name given in"
+        << nl << " * <code>__dbName</code>, and the old database is renamed with a UUID"
+        << nl << " * suffix."
+        << nl << " * @param __connection The Freeze connection associated with this map."
+        << nl << " * @param __dbName The name of the Berkeley DB database."
+        << nl << " * @param __comparator A comparator for the map's main key, or null to use the"
+        << nl << " *   default key comparison strategy."
+        << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+        << nl << " */";
+    out << nl << "public static void" << nl
         << "recreate(Freeze.Connection __connection, String __dbName, "
         << "java.util.Comparator<" << keyTypeS  << "> __comparator)";
     out << sb;
@@ -580,22 +677,52 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
         string indexObjTypeS = typeToObjectString(indexTypes[i]);
         string indexObj = varToObject(indexTypes[i], "__key");
 
-        out << sp << nl << "public Freeze.Map.EntryIterator<java.util.Map.Entry<" << keyTypeS << ", " << valueTypeS
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Obtains an iterator ordered using the index value."
+            << nl << " * The iterator's initial position is an element whose key matches <code>__key</code>; if"
+            << nl << " * no such element exists, the returned iterator is empty (<code>hasNext</code> returns"
+            << nl << " * false). If <code>__onlyDups</code> is true, the iterator only returns elements whose"
+            << nl << " * key exactly matches <code>__key</code>; otherwise, the iterator continues to iterate over"
+            << nl << " * the remaining elements in the map."
+            << nl << " * @param __key The value at which the iterator begins."
+            << nl << " * @param __onlyDups True if the iterator should be limited to elements whose key"
+            << nl << " *   exactly matches <code>__key</code>, false otherwise."
+            << nl << " * @return A new iterator."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public Freeze.Map.EntryIterator<java.util.Map.Entry<" << keyTypeS << ", " << valueTypeS
             << ">>";
         out << nl << "findBy" << capitalizedMembers[i] << "(" << indexTypeS << " __key, boolean __onlyDups)";
         out << sb;
         out << nl << "return _" << members[i] << "Index.find(" << indexObj << ", __onlyDups);";
         out << eb;
 
-        out << sp << nl << "public Freeze.Map.EntryIterator<java.util.Map.Entry<" << keyTypeS << ", " << valueTypeS
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Obtains an iterator ordered using the values of member <code>" << members[i] << "</code>."
+            << nl << " * The iterator's initial position is an element whose key matches <code>__key</code>; if"
+            << nl << " * no such element exists, the returned iterator is empty (<code>hasNext</code> returns"
+            << nl << " * false). This iterator only returns elements whose key exactly matches <code>__key</code>."
+            << nl << " * @param __key The value at which the iterator begins."
+            << nl << " * @return A new iterator."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public Freeze.Map.EntryIterator<java.util.Map.Entry<" << keyTypeS << ", " << valueTypeS
             << ">>";
         out << nl << "findBy" << capitalizedMembers[i] << "(" << indexTypeS << " __key)";
         out << sb;
         out << nl << "return _" << members[i] << "Index.find(" << indexObj << ", true);";
         out << eb;
 
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Determines the number of elements whose index values match <code>__key</code>."
+            << nl << " * @return The number of matching elements."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
         string countMethod = dict.indices[i].member.empty() ?  string("valueCount") : dict.indices[i].member + "Count";
-        out << sp << nl << "public int";
+        out << nl << "public int";
         out << nl << countMethod << "(" << indexTypeS << " __key)";
         out << sb;
         out << nl << "return _" << members[i] << "Index.count(" << indexObj << ");";
@@ -604,33 +731,96 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
         string subMap = "Freeze.NavigableMap<" + indexObjTypeS + ", java.util.Set<java.util.Map.Entry<" + keyTypeS +
             ", " + valueTypeS + ">>>";
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of the portion of this map whose keys are strictly less than"
+            << nl << " * <code>__toKey</code>, or less than or equal to <code>__toKey</code> if"
+            << nl << " * <code>__inclusive</code> is true. Insertions and removals via this map are"
+            << nl << " * not supported."
+            << nl << " * @param __toKey High endpoint of the keys in the returned map."
+            << nl << " * @param __inclusive If true, the endpoint is included in the returned map;"
+            << nl << " *   otherwise, the endpoint is excluded."
+            << nl << " * @return A view of the portion of this map whose keys are strictly less than"
+            << nl << " *   <code>__toKey</code>, or less than or equal to <code>__toKey</code> if"
+            << nl << " *   <code>__inclusive</code> is true."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "headMapFor" << capitalizedMembers[i] << "(" << indexTypeS << " __toKey, boolean __inclusive)";
         out << sb;
         out << nl << "return _" << members[i] << "Index.createHeadMap(" << varToObject(indexTypes[i], "__toKey")
             << ", __inclusive);";
         out << eb;
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of the portion of this map whose keys are strictly less than"
+            << nl << " * <code>__toKey</code>. Insertions and removals via this map are not supported."
+            << nl << " * @param __toKey High endpoint of the keys in the returned map."
+            << nl << " * @return A view of the portion of this map whose keys are strictly less than"
+            << nl << " *   <code>__toKey</code>>"
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "headMapFor" << capitalizedMembers[i] << "(" << indexTypeS << " __toKey)";
         out << sb;
         out << nl << "return headMapFor" << capitalizedMembers[i] << "(__toKey, false);";
         out << eb;
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of the portion of this map whose keys are strictly greater than"
+            << nl << " * <code>__fromKey</code>, or greater than or equal to <code>__fromKey</code> if"
+            << nl << " * <code>__inclusive</code> is true. Insertions and removals via this map are"
+            << nl << " * not supported."
+            << nl << " * @param __fromKey Low endpoint of the keys in the returned map."
+            << nl << " * @param __inclusive If true, the endpoint is included in the returned map;"
+            << nl << " *   otherwise, the endpoint is excluded."
+            << nl << " * @return A view of the portion of this map whose keys are strictly greater than"
+            << nl << " *   <code>__fromKey</code>, or greater than or equal to <code>__fromKey</code> if"
+            << nl << " *   <code>__inclusive</code> is true."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "tailMapFor" << capitalizedMembers[i] << "(" << indexTypeS << " __fromKey, boolean __inclusive)";
         out << sb;
         out << nl << "return _" << members[i] << "Index.createTailMap(" << varToObject(indexTypes[i], "__fromKey")
             << ", __inclusive);";
         out << eb;
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of the portion of this map whose keys are greater than or equal"
+            << nl << " * to <code>__fromKey</code>. Insertions and removals via this map are not supported."
+            << nl << " * @param __fromKey Low endpoint of the keys in the returned map."
+            << nl << " * @return A view of the portion of this map whose keys are greater than or equal"
+            << nl << " *   to <code>__fromKey</code>."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "tailMapFor" << capitalizedMembers[i] << "(" << indexTypeS << " __fromKey)";
         out << sb;
         out << nl << "return tailMapFor" << capitalizedMembers[i] << "(__fromKey, true);";
         out << eb;
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of the portion of this map whose keys range from"
+            << nl << " * <code>__fromKey</code> to <code>__toKey</code>. If <code>__fromKey</code>"
+            << nl << " * and <code>__toKey</code> are equal, the returned map is empty unless"
+            << nl << " * <code>__fromInclusive</code> and <code>__toInclusive</code> are both true."
+            << nl << " * Insertions and removals via this map are not supported."
+            << nl << " * @param __fromKey Low endpoint of the keys in the returned map."
+            << nl << " * @param __fromInclusive If true, the low endpoint is included in the returned map;"
+            << nl << " *   otherwise, the endpoint is excluded."
+            << nl << " * @param __toKey High endpoint of the keys in the returned map."
+            << nl << " * @param __toInclusive If true, the high endpoint is included in the returned map;"
+            << nl << " *   otherwise, the endpoint is excluded."
+            << nl << " * @return A view of the portion of this map whose keys range from"
+            << nl << " *   <code>__fromKey</code> to <code>__toKey</code>."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "subMapFor" << capitalizedMembers[i] << "(" << indexTypeS
             << " __fromKey, boolean __fromInclusive, " << indexTypeS << " __toKey, boolean __toInclusive)";
         out << sb;
@@ -638,14 +828,32 @@ FreezeGenerator::generate(UnitPtr& u, const Dict& dict)
             << ", __fromInclusive, " << varToObject(indexTypes[i], "__toKey") << ", __toInclusive);";
         out << eb;
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of the portion of this map whose keys are greater than"
+            << nl << " * or equal to <code>__fromKey</code> and strictly less than <code>__toKey</code>."
+            << nl << " * Insertions and removals via this map are not supported."
+            << nl << " * @param __fromKey Low endpoint of the keys in the returned map."
+            << nl << " * @param __toKey High endpoint of the keys in the returned map."
+            << nl << " * @return A view of the portion of this map whose keys range from"
+            << nl << " *   <code>__fromKey</code> to <code>__toKey</code>."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "subMapFor" << capitalizedMembers[i] << "(" << indexTypeS << " __fromKey, " << indexTypeS
             << " __toKey)";
         out << sb;
         out << nl << "return subMapFor" << capitalizedMembers[i] << "(__fromKey, true, __toKey, false);";
         out << eb;
 
-        out << sp << nl << "public " + subMap;
+        out << sp;
+        out << nl << "/**"
+            << nl << " * Returns a view of this map whose keys are ordered by the index value."
+            << nl << " * Insertions and removals via this map are not supported."
+            << nl << " * @return A view of this map whose keys range are ordered by the index value."
+            << nl << " * @throws Freeze.DatabaseException If an error occurs during database operations."
+            << nl << " */";
+        out << nl << "public " + subMap;
         out << nl << "mapFor" << capitalizedMembers[i] << "()";
         out << sb;
         out << nl << "return _" << members[i] << "Index.createMap();";
diff --git a/java/src/Freeze/FatalErrorCallback.java b/java/src/Freeze/FatalErrorCallback.java
index 08c6ab6bba5..e610eb5ef7f 100644
--- a/java/src/Freeze/FatalErrorCallback.java
+++ b/java/src/Freeze/FatalErrorCallback.java
@@ -9,7 +9,17 @@
 
 package Freeze;
 
+/**
+ * Handles fatal errors encountered by the background save evictor.
+ */
 public interface FatalErrorCallback
 {
+    /**
+     * Called when the background save evictor encounters a fatal error.
+     *
+     * @param evictor The evictor that detected the error.
+     * @param communicator The communicator associated with the evictor.
+     * @param ex The exception that caused the error.
+     */
     void handleError(Evictor evictor, Ice.Communicator communicator, RuntimeException ex);
 }
diff --git a/java/src/Freeze/NavigableMap.java b/java/src/Freeze/NavigableMap.java
index 646dcc326fd..eab0ecca2a0 100644
--- a/java/src/Freeze/NavigableMap.java
+++ b/java/src/Freeze/NavigableMap.java
@@ -194,7 +194,7 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
     /**
      * 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>.
+     * <code>fromInclusive</code> and <code>toInclusive</code> are both <code>true</code>.
      *<p>
      * Insertions cannot be made via the returned map and must be made on the main map.
      * <p>
@@ -207,10 +207,10 @@ public interface NavigableMap<K, V> extends java.util.SortedMap<K, V>
      *
      * @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>.
+     * <code>false</code>, otherwise.
      * @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>.
+     * <code>false</code>, otherwise.
      * @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);
diff --git a/java/src/Freeze/Util.java b/java/src/Freeze/Util.java
index e2af67a1ecf..62a21d4534e 100644
--- a/java/src/Freeze/Util.java
+++ b/java/src/Freeze/Util.java
@@ -11,6 +11,27 @@ package Freeze;
 
 public class Util
 {
+    /**
+     * Returns a new background save evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param filename The name of the Berkeley DB database file.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new background save evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static BackgroundSaveEvictor
     createBackgroundSaveEvictor(Ice.ObjectAdapter adapter, String envName, String filename,
                                 ServantInitializer initializer, Index[] indices, boolean createDb)
@@ -18,6 +39,28 @@ public class Util
         return new BackgroundSaveEvictorI(adapter, envName, filename, initializer, indices, createDb);
     }
 
+    /**
+     * Returns a new background save evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param dbEnv The database environment in which to open the database.
+     * @param filename The name of the Berkeley DB database file.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new background save evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static BackgroundSaveEvictor
     createBackgroundSaveEvictor(Ice.ObjectAdapter adapter, String envName, com.sleepycat.db.Environment dbEnv,
                                 String filename, ServantInitializer initializer, Index[] indices, boolean createDb)
@@ -25,6 +68,29 @@ public class Util
         return new BackgroundSaveEvictorI(adapter, envName, dbEnv, filename, initializer, indices, createDb);
     }
 
+    /**
+     * Returns a new transactional evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param filename The name of the Berkeley DB database file.
+     * @param facetTypes A map of facet name to Slice type id, or <code>null</code if
+     *   no map is necessary.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new transactional evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static TransactionalEvictor
     createTransactionalEvictor(Ice.ObjectAdapter adapter, String envName, String filename,
                                java.util.Map<String, String> facetTypes, ServantInitializer initializer,
@@ -33,6 +99,30 @@ public class Util
         return new TransactionalEvictorI(adapter, envName, filename, facetTypes, initializer, indices, createDb);
     }
 
+    /**
+     * Returns a new transactional evictor. The Berkeley DB database with the
+     * name given in <code>filename</code> is opened if it already exists.
+     * If the database does not exist yet and <code>createDb</code>
+     * is true, the database is created automatically; otherwise,
+     * <code>DatabaseException</code> is raised.
+     *
+     * @param adapter The object adapter to associate with this evictor.
+     * @param envName The name of the Berkeley DB database environment. The
+     *   environment must already exist.
+     * @param dbEnv The database environment in which to open the database.
+     * @param filename The name of the Berkeley DB database file.
+     * @param facetTypes A map of facet name to Slice type id, or <code>null</code if
+     *   no map is necessary.
+     * @param initializer An object that is used to initialize a servant after its
+     *   state is restored from the database, or <code>null</code> if no initializer
+     *   is necessary.
+     * @param indices An array of Freeze indices, or <code>null</code if no indices
+     *   are defined.
+     * @param createDb True if the Berkeley DB database should be created if it does
+     *   not exist, false otherwise.
+     * @return A new transactional evictor.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static TransactionalEvictor
     createTransactionalEvictor(Ice.ObjectAdapter adapter, String envName, com.sleepycat.db.Environment dbEnv,
                                String filename, java.util.Map<String, String> facetTypes,
@@ -41,30 +131,65 @@ public class Util
         return new TransactionalEvictorI(adapter, envName, dbEnv, filename, facetTypes, initializer, indices, createDb);
     }
 
+    /**
+     * Creates a new Freeze connection using the given communicator and database
+     * environment.
+     *
+     * @param communicator The communicator associated with this connection.
+     * @param envName The name of the Berkeley DB database environment.
+     * @return A new Freeze connection.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static Connection
     createConnection(Ice.Communicator communicator, String envName)
     {
         return new ConnectionI(communicator, envName, null);
     }
 
+    /**
+     * Creates a new Freeze connection using the given communicator and database
+     * environment.
+     *
+     * @param communicator The communicator associated with this connection.
+     * @param envName The name of the Berkeley DB database environment.
+     * @param dbEnv The database environment associated with this connection.
+     * @return A new Freeze connection.
+     * @throws Freeze.DatabaseException If an error occurs during database operations.
+     */
     public static Connection
     createConnection(Ice.Communicator communicator, String envName, com.sleepycat.db.Environment dbEnv)
     {
         return new ConnectionI(communicator, envName, dbEnv);
     }
 
+    /**
+     * Returns the database file name of the Freeze catalog.
+     *
+     * @return The database file name.
+     */
     public static String
     catalogName()
     {
         return _catalogName;
     }
 
+    /**
+     * Returns the database file name of the Freeze catalog index list.
+     *
+     * @return The database file name.
+     */
     public static String
     catalogIndexListName()
     {
         return _catalogIndexListName;
     }
 
+    /**
+     * Returns the Berkeley DB transaction object associated with a Freeze transaction.
+     *
+     * @param tx The Freeze transaction.
+     * @return The Berkeley DB transaction.
+     */
     public static com.sleepycat.db.Transaction
     getTxn(Transaction tx)
     {
@@ -78,6 +203,11 @@ public class Util
         }
     }
 
+    /**
+     * Registers a handler for fatal errors encountered by the background save evictor.
+     *
+     * @param cb The error callback.
+     */
     public static synchronized FatalErrorCallback
     registerFatalErrorCallback(FatalErrorCallback cb)
     {