minor documentation updates

4 files changed, 33 insertions, 26 deletions

diff --git a/CHANGES b/CHANGES
index 1cc1a95..b249400 100644
--- a/CHANGES
+++ b/CHANGES
@@ -14,12 +14,11 @@ Overview
 
     Welcome to Passlib 1.6.
 
-    The main goal of this release was to clean up the codebase, reducing
-    the amount of internally-redundant code, and to simplify the publically
-    exposed interface. It also brings with it a number of other improvements:
-    10 or so new hash algorithms, additional security precautions
-    for the existing algorithms, a number of speed improvements,
-    and reorganized documentation.
+    The main goals of this release were to clean up the codebase, tighten input 
+    validation, and simplify the publically exposed interfaces. This release also 
+    brings with it a number of other improvements: 10 or so new hash algorithms, 
+    additional security precautions for the existing algorithms, 
+    a number of speed improvements, and updated documentation.
 
 Deprecated APIs
 ...............
@@ -101,7 +100,7 @@ Existing Hashes
         which exploits short-circuit string comparisons.
         While this attack is not currently feasible against
         most password hashes, some of the weaker unsalted
-        hashes supported Passlib may be vulnerable; and this
+        hashes supported by Passlib may be vulnerable; and this
         change has been made preventatively to all of them.
 
         .. [#consteq] "constant time" is a misnomer, it actually takes ``THETA(len(righthand_value))`` time.
diff --git a/docs/lib/passlib.hash.unix_disabled.rst b/docs/lib/passlib.hash.unix_disabled.rst
index 8a8fece..a112147 100644
--- a/docs/lib/passlib.hash.unix_disabled.rst
+++ b/docs/lib/passlib.hash.unix_disabled.rst
@@ -23,14 +23,14 @@ It can be used directly as follows::
     >>> unix_disabled.verify("letmein", "*NOPASSWORD*")
     False
 
-    >>> # this class will positively identify all strings - so if it's used
-    >>> # in conjunction with other hashes, this should be the last one checked.
+    >>> # this class should identify all strings which aren't
+    >>> # valid Unix crypt() output, while leaving MCF hashes alone
     >>> unix_disabled.identify('!')
     True
-    >>> unix_disabled.identify('*')
-    True
     >>> unix_disabled.identify('')
     True
+    >>> unix_disabled.identify("$1$somehash")
+    False
 
 Interface
 =========
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index 3aef350..fbaf38d 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -259,10 +259,10 @@ and hash comparison.
       otherwise non-ASCII passwords may not :meth:`!verify` successfully.
 
     * For historical reasons, :class:`~passlib.hash.lmhash` uses ``cp437``
-      as it's default encoding. It will handle :class:`!unicode` correctly,
-      but non-``ascii`` passwords provided as :class:`!bytes` must be encoded
-      using ``"cp437"``, or the correct encoding must be specified via :class:`!lmhash`'s
-      ``encoding`` keyword.
+      as it's default encoding. It will handle :class:`!unicode` correctly;
+      but non-ASCII passwords provided as :class:`!bytes` must either be encoded
+      using ``"cp437"``, or :class:`!lmhash`'s ``encoding`` keyword must
+      be set to indicate which encoding was used.
 
 .. _crypt-methods:
 
@@ -272,7 +272,7 @@ Taken together, the :meth:`~PasswordHash.genconfig` and :meth:`~PasswordHash.gen
 are two tightly-coupled methods that mimic the standard Unix
 "crypt" interface. The first method generates salt / configuration
 strings from a set of settings, and the second hashes the password
-using the provided configuration string.
+using the provided configuration string. 
 
 .. seealso::
 
@@ -377,14 +377,17 @@ There is currently one additional support method, :meth:`~PasswordHash.identify`
     :returns:
         * ``True`` if the input is a configuration string or hash string
            identifiable as belonging to this scheme (even if it's malformed).
-        * ``False`` if the input does *not* belong to this scheme.
-        * Hashes which lack a reliable method of identification may incorrectly
-          identify each-other's hashes (e.g. both :class:`~passlib.hash.lmhash`
-          and :class:`~passlib.hash.nthash` hash consist 32 hexidecimal characters).
+        * ``False`` if the input does not belong to this scheme.
 
     :raises TypeError:
         if :samp:`{hash}` is not a unicode or bytes instance.
 
+    .. note::
+
+        Hashes which lack a reliable method of identification may incorrectly
+        identify each-other's hashes (e.g. both :class:`~passlib.hash.lmhash`
+        and :class:`~passlib.hash.nthash` hash consist 32 hexidecimal characters).
+
     .. seealso::
 
         If you are considering using this method to select from multiple
@@ -456,11 +459,13 @@ the hashes in passlib:
     ``salt_size``
 
         Most algorithms which support the ``salt`` setting will
-        autogenerate a salt when none is provided. Many of those
+        autogenerate a salt when none is provided. Most of those hashes
         will also offer this option, which allows the caller to specify
         the size of salt which should be generated. If omitted,
         the hash's default salt size will be used.
 
+        .. seealso:: the :ref:`salt info <salt-attributes>` attributes (below)
+
     .. index:: 
         single: rounds; PasswordHash keyword
 
@@ -479,6 +484,8 @@ the hashes in passlib:
         are periodically retuned to strike a balance between
         security and responsiveness.
 
+        .. seealso:: the :ref:`rounds info <rounds-attributes>` attributes (below)
+
     .. index:: 
         single: ident; PasswordHash keyword
 
@@ -539,8 +546,8 @@ the hashes in passlib:
     ``encoding``
 
         Some hashes have poorly-defined or host-dependant unicode behavior,
-        and properly hashing a unique password requires providing
-        the correct encoding (e.g. :class:`~passlib.hash.lmhash`).
+        and properly hashing a non-ASCII password requires providing
+        the correct encoding (:class:`~passlib.hash.lmhash` is perhaps the worst offender).
         Hashes which provide this keyword will always expose
         their default encoding programmatically via the
         :attr:`~PasswordHash.default_encoding` attribute.
@@ -574,9 +581,10 @@ and the following attributes should be defined:
 .. attribute:: PasswordHash.salt_chars
 
     A unicode string containing all the characters permitted
-    in a salt string. For most :ref:`MCF <modular-crypt-format>` hashes,
-    this is equal to :data:`passlib.utils.HASH64_CHARS`.
+    in a salt string. 
 
+    For most :ref:`modular-crypt-format` hashes,
+    this is equal to :data:`passlib.utils.HASH64_CHARS`.
     For the rare hashes where the ``salt`` parameter must be specified
     in bytes, this will be a placeholder :class:`!bytes` object containing
     all 256 possible byte values.
diff --git a/passlib/context.py b/passlib/context.py
index 19bc904..dca68ae 100644
--- a/passlib/context.py
+++ b/passlib/context.py
@@ -1830,7 +1830,7 @@ class CryptContext(object):
     ##    return kwds
 
     def handler(self, scheme=None, category=None):
-        """helper to resolve name of scheme -> handler object.
+        """helper to resolve name of scheme -> :class:`~passlib.ifc.PasswordHash` object used by scheme.
 
         :arg scheme:
             This should identify the scheme to lookup.