search: Improve Bsearch documentation.

The documentation did not clearly explain how to use the macro to search
for slightly modified boundary conditions.

Author: lorinder

src/csnip/search.h

@@ -27,9 +27,10 @@
 
 /** Binary search.
  *
- *  Statement macro. Find the smallest index i in a sorted array such
- *  that the i-th entry is at least as large as a specified key.  If no
- *  such index exists return N, the size of the array.
+ *  Statement macro. Find the smallest index i in an ascending sorted
+ *  array a such that a[i] >= key, i.e.,  the i-th entry is at least as
+ *  large as a specified key.  If no such index exists, i.e., a[i] < key
+ *  for all i, return N, the size of the array.
  *
  *  @param	itype
  *		integral type used for the return value. itype is also
@@ -50,10 +51,26 @@
  *		lvalue of type itype to store the result index.
  *
  *  @note	By default the csnip_Bsearch function finds the
- *		lowest index i such that a[i] >= key. To find
- *		the lowest index such that a[i] > key, the
- *		au_lessthan_key expression can be set to a
- *		less-than-or-equal expression.
+ *		lowest index i such that a[i] >= key.  The following
+ *		alternative uses are possible:
+ *
+ *		- To find the lowest index i such that a[i] > key, the
+ *		  au_lessthan_key expression can be set to a
+ *		  less-than-or-equal expression.
+ *
+ *		- To find the largest index such that a[i] <= key, set
+ *		  the au_lessthan_key expression to a
+ *		  less-than-or-equal, and subtract 1 from the result.
+ *		  Returns (itype)-1 if no such index exists.
+ *
+ *		- To find the largest index i such that a[i] < key, set
+ *		  the au_lessthan_key expression to a less-than
+ *		  expression, and subtract 1 from the result.  The
+ *		  return value (itype)-1 means that no such index
+ *		  exists.
+ *
+ *		If the array is sorted in a descending manner, the
+ *		comparation expression can be reverted.
  */
 #define csnip_Bsearch(itype, u, au_lessthan_key, N, ret) \
 	csnip__Bsearch(itype, u, au_lessthan_key, (N), (ret), \
@@ -65,7 +82,7 @@
 	do { \
 		/* loop invariants:
 		 * a[0], ..., a[lo - 1] < key;
-		 * a[hi], ..., a[N - 1] >= key;
+		 * a[hi], ..., a[N - 1] >= key.
 		 */ \
 		itype lo = 0; \
 		itype hi = N; \