From f1b56d292bbe248bf29c078d27986cdfbb1b3d39 Mon Sep 17 00:00:00 2001
From: Martin Mares <mj@ucw.cz>
Date: Thu, 6 Sep 2007 22:00:10 +0200
Subject: [PATCH] A few bits of commentary.

---
 lib/sorter/array.c |  2 +-
 lib/sorter/array.h | 20 ++++++++++++++------
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/lib/sorter/array.c b/lib/sorter/array.c
index 65a11921..a6c217e8 100644
--- a/lib/sorter/array.c
+++ b/lib/sorter/array.c
@@ -7,7 +7,7 @@
  *	of the GNU Lesser General Public License.
  */
 
-#define LOCAL_DEBUG
+#undef LOCAL_DEBUG
 
 #include "lib/lib.h"
 #include "lib/sorter/common.h"
diff --git a/lib/sorter/array.h b/lib/sorter/array.h
index 1370baa5..ef1d0551 100644
--- a/lib/sorter/array.h
+++ b/lib/sorter/array.h
@@ -8,11 +8,14 @@
  */
 
 /*
- *  This is a generator of routines for sorting arrays, very similar to the one
- *  in lib/arraysort.h.
+ *  This is a generator of routines for sorting huge arrays, similar to the one
+ *  in lib/arraysort.h. It cannot handle discontiguous arrays, but it is able
+ *  to employ radix-sorting if a monotone hash function is available and also
+ *  use several threads in parallel on SMP systems (this assumes that all
+ *  callbacks you provide are thread-safe).
  *
- *  FIXME: <comments>
- *  FIXME: Note on thread-safety
+ *  It is usually called internally by the generic shorter machinery, but
+ *  you are free to use it explicitly if you need.
  *
  *  So much for advocacy, there are the parameters (those marked with [*]
  *  are mandatory):
@@ -23,13 +26,18 @@
  *  ASORT_LT(x,y)	x < y for ASORT_TYPE (default: "x<y")
  *  ASORT_THRESHOLD	threshold for switching between quicksort and insertsort
  *  ASORT_PAGE_ALIGNED	the array is guaranteed to be aligned to a multiple of CPU_PAGE_SIZE  (FIXME: Do we need this?)
- *  ASORT_HASH(x)	FIXME
+ *  ASORT_HASH(x)	a monotone hash function (safisfying hash(x) < hash(y) => x<y)
  *  ASORT_RADIX_BITS	FIXME
  *  ASORT_SWAP		FIXME: probably keep private
  *
  *  After including this file, a function
  * 	ASORT_KEY_TYPE *ASORT_PREFIX(sort)(ASORT_KEY_TYPE *array, uns num_elts, ASORT_KEY_TYPE *buf, uns hash_bits)
- *  is declared and all parameter macros are automatically undef'd.
+ *  is declared and all parameter macros are automatically undef'd. Here `buf' is an
+ *  auxiliary buffer of the same size as the input array, required whenever radix
+ *  sorting should be used, and `hash_bits' is the number of significant bits returned
+ *  by the hash function. If the buffer is specified, the sorting function returns either
+ *  a pointer to the input array or to the buffer, depending on where the result is stored.
+ *  If you do not use hashing, these parameters should be NULL and 0, respectively.
  */
 
 #include "lib/sorter/common.h"
-- 
2.39.2