Improve documentation

Author: sethrj

doc/examples.rst

@@ -9,16 +9,11 @@ Examples
 The following standalone codes demonstrate how Flibcpp can be used in native
 Fortran code.
 
-String conversion and sort
+Random numbers and sorting
 ==========================
 
-This example:
-
- - Introspects the Flibcpp version;
- - Converts a user input to an integer, validating it with useful error
-   messages;
- - Fills an array with normally-distributed real numbers; and
- - Sorts the array before printing the first few entries.
+This simple example generates an array of normally-distributed double-precision
+reals, sorts them, and then shuffles them again.
 
 .. literalinclude:: ../example/sort.f90
    :linenos:
@@ -32,6 +27,39 @@ from native Fortran strings.
 .. literalinclude:: ../example/vecstr.f90
    :linenos:
 
+.. _example_generic:
+
+Generic sorting
+===============
+
+Since sorting algorithms often allow :math:`O(N)` algorithms to be written in
+:math:`O(\log N)`, providing generic sorting routines is immensely useful in
+applications that operate on large chunks of data. This example demonstrates
+the generic version of the :ref:`modules_algorithm_argsort` subroutine by
+sorting a native Fortran array of native Fortran types using a native Fortran
+subroutine. The only C interaction needed is to create C pointers to the
+Fortran array entries and to provide a C-bound comparator that converts those
+pointers back to native Fortran pointers.
+
+.. literalinclude:: ../example/sort_generic.f90
+   :linenos:
+
+.. _example_utils:
+
+Example utilities module
+========================
+
+This pure-Fortran module builds on top of functionality from Flibcpp. It
+provides procedures to:
+
+ - Format and print the Flibcpp version;
+ - Converts a user input to an integer, validating it with useful error
+   messages;
+ - Reads a dynamically sized vector of strings from the user.
+
+.. literalinclude:: ../example/example_utils.f90
+   :linenos:
+
 .. ############################################################################
 .. end of doc/examples.rst
 .. ############################################################################

doc/modules/algorithm.rst

@@ -21,7 +21,17 @@ Sorting
 
 Sorting algorithms for numeric types default to increasing order when provided
 with a single array argument. Numeric sorting routines accept an optional
-second argument, a comparator function,
+second argument, a comparator function, which should return ``true`` if the
+first argument is strictly less than the right-hand side.
+
+.. warning:: For every value of ``a`` and ``b``, the comparator ``cmp`` *must*
+   satisfy ``.not. (cmp(a, b) .and. cmp(b, a))``. If this strict ordering is
+   not satisfied, some of the algorithms below may crash the program.
+
+All sorting algorithms are *also* instantiated so that they accept an array of
+``type(C_PTR)`` and a generic comparator function. **This enables arrays of any
+native Fortran object to be sorted**. See :ref:`the generic
+sorting example <example_generic>` for a demonstration.
 
 sort
 ----
@@ -45,6 +55,8 @@ Checking the ordering of array is just as simple::
 
   sortitude = is_sorted(iarr)
 
+.. _modules_algorithm_argsort:
+
 argsort
 -------
 
@@ -75,6 +87,10 @@ zero.
 Searching
 =========
 
+Like the sorting algorithms, searching algorithms are instantiated on numeric
+types and the C pointer type, and they provide an optional procedure pointer
+argument that allows the arrays to be ordered with an arbitrary comparator.
+
 .. _modules_algorithm_binary_search:
 
 binary_search