Update documentation

Author: sethrj

doc/index.rst

@@ -31,7 +31,7 @@ which wrap the C++ library.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
 
    introduction.rst
    modules.rst

doc/modules/algorithm.rst

@@ -12,9 +12,9 @@ The ``flc_algorithm`` module wraps C++ standard `<algorithm>`_ routines.
 Instead of taking pairs of iterators, the Flibcpp algorithm subroutines accept
 target-qualified 1-D arrays.
 
-Algorithms that take comparators (e.g. sort) will be instantiated with function
-pointers that allow user functions to add arbitrary ordering by defining
-``bind(C)`` functions and calling with ``c_funloc(my_comparator)``.
+Algorithms that take comparators (e.g. sorting and searching) are instantiated
+with function pointers that allow user functions to add arbitrary ordering by
+defining ``bind(C)`` functions and calling with ``c_funloc(my_comparator)``.
 
 Wherever possible, array indices are returned as Fortran 1-offset native
 integers, with the value 0 indicating off-the-end (e.g. "not found").
@@ -24,21 +24,31 @@ integers, with the value 0 indicating off-the-end (e.g. "not found").
 Sorting
 =======
 
-All sorting functions
-
-Sort
+sort
 ----
 
 Sorting and checking order is a single simple subroutine call::
 
-  use flc_algorithm, only : sort, is_sorted
+  use flc_algorithm, only : sort
   implicit none
   integer, dimension(5) :: iarr = [ 2, 5, -2, 3, -10000]
-  logical :: sortitude
 
   call sort(iarr)
+
+is_sorted
+---------
+
+Checking the ordering of array is just as simple::
+
+  use flc_algorithm, only : is_sorted
+  integer, dimension(5) :: iarr = [ 2, 5, -2, 3, -10000]
+  logical :: sortitude
+
   sortitude = is_sorted(iarr)
 
+argsort
+-------
+
 A routine that provides the indices that correspond to a sorted array, like
 Numpy's argsort_ ,
 takes an array to analyze and an empty array of integers to fill::
@@ -61,9 +71,13 @@ the index array is larger than the data, invalid entries will be filled with
 zero.
 
 .. _argsort: https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.argsort.html
+
 Searching
 =========
 
+binary_search
+-------------
+
 A binary search can be performed on sorted data to efficiently find an element
 in a range. If the element is not found, the function returns zero; otherwise,
 it returns the Fortran index of the array.
@@ -84,25 +98,54 @@ Example::
   idx = binary_search(iarr, 9)    ! returns 6
   idx = binary_search(iarr, 10)   ! returns 0
 
+minmax_element
+--------------
+
+TODO
 
 Set operations
 ==============
 
 Sorted arrays can be manipulated as "sets," supporting unions, intersections,
 and differences. TODO.
 
+includes
+--------
+
+TODO
+
+set_difference
+--------------
+
+TODO
+
+set_intersection
+----------------
+
+TODO
+
+set_symmetric_difference
+------------------------
+
+TODO
+
+set_union
+---------
+
+TODO
+
 Modifying
 =========
 
 .. _modules_algorithm_shuffle:
 
-Shuffle
+shuffle
 -------
 
-The ``algorithm`` module depends on the ``random`` module so that it can use
-the supported random number generator to randomly reorder an array.
+The "shuffle" subroutine depends on the :ref:`modules_random` module so that it
+can use the supported random number generator to randomly reorder an array.
 
-Unique
+unique
 ------
 
 TODO

doc/modules/random.rst

@@ -51,16 +51,30 @@ Its interface is::
      module procedure new_Engine
     end interface
 
-Normal distribution
-===================
+Distributions
+=============
 
-Uniform integer distribution
-============================
+Distributions produce numerical values from the random bitstream provided by
+the Engine.
 
-Uniform real distribution
-=========================
+normal_distribution
+-------------------
 
+Fill the given array with Gaussian-distributed numbers generated using the
+given random number engine about the given mean value with the given standard
+deviation, which defaults to 1.
 
+uniform_int_distribution
+------------------------
+
+Fill the given array with uniformly distributed integers generated using the
+given random number engine, between the two bounds (inclusive on both sides).
+
+uniform_real_distribution
+-------------------------
+
+Fill the given array with uniformly distributed real numbers generated using the
+given random number engine, between the two bounds (inclusive on left side only).
 
 
 .. ############################################################################