Comments added and improved.

(dump_l2g_stats): New function.

src/server/local-to-global.h

@@ -10,53 +10,65 @@
 
 #include "kom-types.h"
 
-void             l2g_destruct(Local_to_global *l2g);
+/* Contstructor.  Take raw memory and create an empty
+   Local_to_global mapping. */
+void l2g_init(Local_to_global *l2g);
 
-void             l2g_init    (Local_to_global *l2g);
-void             l2g_clear   (Local_to_global *l2g);
-void             l2g_copy    (Local_to_global *dest,
-			      const Local_to_global *src);
+/* Destructor.  Frees all memory associated with ``l2g'' and destruct
+   the object, turning it into raw memory once again.  */
+void l2g_destruct(Local_to_global *l2g);
+
+/* Re-initialize ``l2g''.  "lg2_clear(&foo)" is equivalent to
+   "l2g_destruct(&foo); l2g_init(&foo)" but slightly more efficient. */
+void l2g_clear(Local_to_global *l2g);
+
+/* Copy ``src'' to ``dest''.  Both ``src'' and ``dest'' must be
+   constructed Local_to_global objects.  This operation will ensure
+   that they contain the same data.  */
+void l2g_copy(Local_to_global *dest, const Local_to_global *src);
 
 /* Append a new mapping from LNO to TNO.  LNO must be higher than any
    LNO previously stored in the structure.
    Invalidates all iterators.  */
-void             l2g_append  (Local_to_global *l2g, Local_text_no lno, 
-			                            Text_no       tno);
+void l2g_append(Local_to_global *l2g, Local_text_no lno, Text_no tno);
+
 /* Delete LNO from the structure.  Invalidates all iterators.  */
-void             l2g_delete  (Local_to_global *l2g, Local_text_no lno);
+void l2g_delete(Local_to_global *l2g, Local_text_no lno);
 
 /* Return the TNO previously stored under LNO.  Returns 0 if no such
    LNO exists.  */
-Text_no          l2g_lookup  (const Local_to_global *l2g, Local_text_no lno);
+Text_no l2g_lookup(const Local_to_global *l2g, Local_text_no lno);
 
 /* Returns the next local text number, or 0 if lno is larger than the
    largest local text number.  */
-Local_text_no    l2g_next_key(const Local_to_global *l2g, Local_text_no lno);
+Local_text_no l2g_next_key(const Local_to_global *l2g, Local_text_no lno);
 
 /* Returns the lowest local text number that has never been present in
-   the structure.  This is the same as one plus the highest local text number
-   that is present in the structure (unless it has been deleted --
-   deletions do not cause this to decrease).  Returns 1 if the
+   the structure.  This is the same as one plus the highest local text
+   number that is present in the structure (unless it has been deleted
+   -- deletions do not cause this to decrease).  Returns 1 if the
    structure has always been empty. */
-Local_text_no    l2g_first_appendable_key(const Local_to_global *l2g);
+Local_text_no l2g_first_appendable_key(const Local_to_global *l2g);
 
 /* Delete global text number TNO.  This function can only be called if
    both the local and global text numbers are monotonous series, as
    they are in the Person::created_text_map field. */
 void l2g_delete_global_in_sorted(Local_to_global *l2g, Text_no tno);
 
-/* Text file representation, e.g. for the database. */
-
 /* Dump all internal state.  This is used by the test suite to peek at
    the internal representation.  It should not be used except for such
    debugging purposes. */
-void             l2g_dump    (FILE *file, const Local_to_global *l2g);
+void l2g_dump(FILE *file, const Local_to_global *l2g);
+
+/* Write an external representation of the mapping to ``file''. */
+void l2g_write(FILE *file, const Local_to_global *l2g);
+
+/* Initialize the mapping from the representation found in ``file''. */
+Success l2g_read(FILE *file, Local_to_global *l2g);
 
-/* Write an external representation of the mapping to a file. */
-void             l2g_write   (FILE *file, const Local_to_global *l2g);
+/* Dump global usage statistics to ``file''. */
+void dump_l2g_stats(FILE *file);
 
-/* Initialize the mapping from the representation found in file. */
-Success          l2g_read    (FILE *file, Local_to_global *l2g);
 
 
 /* ================================================================ */