diff --git a/VERSION b/VERSION
--- a/VERSION
+++ b/VERSION
@@ -1,3 +1,5 @@
+0.1.0.1 (2013.06.01):
+    - Documentation changes.
 0.1.0 (2013.05.29):
     - forked from the (unpublished) data-fin package.
     - made things Trustworthy, and some other cleanup.
diff --git a/prelude-safeenum.cabal b/prelude-safeenum.cabal
--- a/prelude-safeenum.cabal
+++ b/prelude-safeenum.cabal
@@ -1,5 +1,5 @@
 ----------------------------------------------------------------
--- wren ng thornton <wren@community.haskell.org>    ~ 2013.05.29
+-- wren ng thornton <wren@community.haskell.org>    ~ 2013.06.01
 ----------------------------------------------------------------
 
 -- By and large Cabal >=1.2 is fine; but >= 1.6 gives tested-with:
@@ -8,7 +8,7 @@
 Build-Type:     Simple
 
 Name:           prelude-safeenum
-Version:        0.1.0
+Version:        0.1.0.1
 Stability:      provisional
 Homepage:       http://code.haskell.org/~wren/
 Author:         wren ng thornton
diff --git a/src/Data/Number/CalkinWilf.hs b/src/Data/Number/CalkinWilf.hs
--- a/src/Data/Number/CalkinWilf.hs
+++ b/src/Data/Number/CalkinWilf.hs
@@ -5,7 +5,7 @@
 {-# LANGUAGE Trustworthy #-}
 #endif
 ----------------------------------------------------------------
---                                                    2013.05.29
+--                                                    2013.06.01
 -- |
 -- Module      :  Data.Number.CalkinWilf
 -- Copyright   :  2012--2013 wren ng thornton
@@ -14,7 +14,14 @@
 -- Stability   :  provisional
 -- Portability :  Haskell98 + CPP + GeneralizedNewtypeDeriving
 --
--- Enumerate the rationals in Calkin--Wilf order.
+-- Enumerate the rationals in Calkin--Wilf order. That is, when we
+-- give enumeration a well-specified meaning (as "Prelude.SafeEnum"
+-- does) this renders instances for 'Ratio' problematic. 'Ratio'
+-- instances /can/ be provided so long as the base type is integral
+-- and enumerable; but they must be done in an obscure order that
+-- does not coincide with the 'Ord' instance for 'Ratio'. Since
+-- this is not what people may expect, we only provide an instance
+-- for the newtype 'CalkinWilf', not for 'Ratio' itself.
 --
 --   * Jeremy Gibbons, David Lester, and Richard Bird (2006).
 --     /Enumerating the Rationals/. JFP 16(3):281--291.
diff --git a/src/Prelude/SafeEnum.hs b/src/Prelude/SafeEnum.hs
--- a/src/Prelude/SafeEnum.hs
+++ b/src/Prelude/SafeEnum.hs
@@ -7,7 +7,7 @@
 {-# LANGUAGE Trustworthy #-}
 #endif
 ----------------------------------------------------------------
---                                                    2013.05.29
+--                                                    2013.06.01
 -- |
 -- Module      :  Prelude.SafeEnum
 -- Copyright   :  2012--2013 wren ng thornton
@@ -36,10 +36,11 @@
 -- ensure that the notion of enumeration (in either direction) is
 -- well-defined, which rules out instances for 'Float' and 'Double',
 -- and renders instances for 'Ratio' problematic. 'Ratio' instances
--- /can/ be provided so long as the base type is enumerable (and
--- 'Integral', naturally); but they must be done in an obscure
--- order[2] that does not coincide with 'Ord', which is not what
--- people expect.
+-- /can/ be provided so long as the base type is integral and
+-- enumerable; but they must be done in an obscure order[2] that
+-- does not coincide with 'Ord'. Since this is not what people may
+-- expect, we only provide an instance for the newtype 'CalkinWilf',
+-- not for 'Ratio' itself.
 --
 -- The @MagicHash@ extension is only actually required if on GHC.
 -- This extension is used only so that the implementation of the
@@ -75,9 +76,13 @@
 
 ----------------------------------------------------------------
 -- | A class for upward enumerable types. That is, we can enumerate
--- larger and larger values, eventually getting all of them. We
--- require that 'succeeds' forms a strict partial order. That is,
--- it must obey the following laws (N.B., if the first two laws
+-- larger and larger values, eventually getting every one of them;
+-- i.e., given any @x@, for all @y@ such that @y \`succeeds\` x@,
+-- it must be the case that @y@ occurs within some finite prefix
+-- of @enumFrom x@.
+--
+-- We require that 'succeeds' forms a strict partial order. That
+-- is, it must obey the following laws (N.B., if the first two laws
 -- hold, then the third one follows for free):
 --
 -- > if x `succeeds` y && y `succeeds` z then x `succeeds` z
@@ -153,9 +158,13 @@
 
 ----------------------------------------------------------------
 -- | A class for downward enumerable types. That is, we can enumerate
--- smaller and smaller values, eventually getting all of them. We
--- require that 'precedes' forms a strict partial order. That is,
--- it must obey the following laws (N.B., if the first two laws
+-- smaller and smaller values, eventually getting every one of them;
+-- i.e., given any @x@, for all @y@ such that @y \`precedes\` x@,
+-- it must be the case that @y@ occurs within some finite prefix
+-- of @enumDownFrom x@.
+--
+-- We require that 'precedes' forms a strict partial order. That
+-- is, it must obey the following laws (N.B., if the first two laws
 -- hold, then the third one follows for free):
 --
 -- > if x `precedes` y && y `precedes` z then x `precedes` z