various minor updates to documentation & code comments

5 files changed, 34 insertions, 18 deletions

diff --git a/CHANGES b/CHANGES
index 433deb2..0c58167 100644
--- a/CHANGES
+++ b/CHANGES
@@ -9,10 +9,10 @@ Release History
 
     Minor bugfix release
     
-    * FreeBSD 8.3+ has native support for SHA512-Crypt,
-      updated unittests and documentation accordingly (:issue:`35`)
+    * *bugfix*: FreeBSD 8.3 added native support for SHA512-Crypt,
+      updated unittests and documentation accordingly (:issue:`35`).
       
-    * Fixed bug in passlib.apache unittest which caused test to fail
+    * *bugfix:* Fixed bug in passlib.apache unittest which caused test to fail
       if filesystem had mtime resolution >= 1 second (:issue:`35`). 
       
     * Various documentation updates and corrections.
diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst
index b48f719..522213a 100644
--- a/docs/lib/passlib.hash.pbkdf2_digest.rst
+++ b/docs/lib/passlib.hash.pbkdf2_digest.rst
@@ -73,7 +73,7 @@ An example :class:`!pbkdf2_sha256` hash (of ``password``)::
 All of the pbkdf2 hashes defined by passlib
 follow the same format, :samp:`$pbkdf2-{digest}${rounds}${salt}${checksum}`.
 
-* :samp:`$pbkdf2-{digest}$`` is used as the :ref:`modular-crypt-format` identifier
+* :samp:`$pbkdf2-{digest}$` is used as the :ref:`modular-crypt-format` identifier
   (``$pbkdf2-sha256$`` in the example).
 
 * :samp:`{digest}` - this specifies the particular cryptographic hash
@@ -96,7 +96,7 @@ follow the same format, :samp:`$pbkdf2-{digest}${rounds}${salt}${checksum}`.
 
 The algorithm used by all of these schemes is deliberately identical and simple:
 The password is encoded into UTF-8 if not already encoded,
-and passed through :func:`~passlib.utils.pbkdf2.pbkdf2`
+and run through :func:`~passlib.utils.pbkdf2.pbkdf2`
 along with the decoded salt, the number of rounds,
 and a prf built from HMAC + the respective message digest.
 The result is then encoded using :func:`~passlib.utils.ab64_encode`.
diff --git a/docs/modular_crypt_format.rst b/docs/modular_crypt_format.rst
index bab73d1..aa564fb 100644
--- a/docs/modular_crypt_format.rst
+++ b/docs/modular_crypt_format.rst
@@ -128,7 +128,7 @@ and indicates which operating systems offer native support for them [#gae]_.
 ==================================== ==================== =========== =========== =========== =========== ======= =======
 Scheme                               Prefix               Linux       FreeBSD     NetBSD      OpenBSD     Solaris MacOSX
 ==================================== ==================== =========== =========== =========== =========== ======= =======
-:class:`~passlib.hash.des_crypt`     none                 y           y           y           y           y       y
+:class:`~passlib.hash.des_crypt`                          y           y           y           y           y       y
 :class:`~passlib.hash.bsdi_crypt`    ``_``                            y           y           y                   y
 :class:`~passlib.hash.md5_crypt`     ``$1$``              y           y           y           y           y
 :class:`~passlib.hash.sun_md5_crypt` ``$md5$``, ``$md5,``                                                 y
diff --git a/docs/password_hash_api.rst b/docs/password_hash_api.rst
index fbaf38d..8d136c2 100644
--- a/docs/password_hash_api.rst
+++ b/docs/password_hash_api.rst
@@ -67,6 +67,7 @@ using the :class:`~passlib.hash.sha256_crypt` hash as an example::
     >>> # you can override the default value via the 'rounds' keyword:
     >>> sha256_crypt.encrypt("password", rounds=12345)
     '$5$rounds=12345$UeVpHaN2YFDwBoeJ$NJN8DwVZ4UfQw6.ijJZNWoZtk1Ivi5YfKCDsI2HzSq2'
+               ^^^^^
 
     >>> # on the other end of things, the verify() method takes care of
     >>> # checking if a password matches an existing hash string:
@@ -146,8 +147,13 @@ and hash comparison.
 
 .. classmethod:: PasswordHash.encrypt(secret, \*\*kwds)
 
-    Encrypt password, returning resulting hash string.
-
+    Digest password using format-specific algorithm,
+    returning resulting hash string.
+    
+    For most hashes supported by Passlib, this string will include
+    an algorithm identifier, a copy of the salt (if applicable),
+    and any other configuration information required to verify the password later.
+    
     :type secret: unicode or bytes
     :arg secret: string containing the password to encode.
 
@@ -157,28 +163,32 @@ and hash comparison.
         in that hash's documentation; though many of the more common keywords
         are listed under :attr:`~PasswordHash.setting_kwds`
         and :attr:`~PasswordHash.context_kwds`.
-        Examples of common keywords include ``salt`` and ``rounds``.
+        Examples of common keywords include ``rounds`` and ``salt_size``.
 
     :returns:
-        resulting hash, using an algorithm-specific format.
+        Resulting hash of password, using an algorithm-specific format.
 
-        this will use the native :class:`!str` type
-        (unicode under Python 3, ``ascii``-encoded bytes under Python 2).
+        This will always be an instance of :class:`!str`
+        (i.e. :class:`unicode` under Python 3, ``ascii``-encoded :class:`bytes` under Python 2).
 
     :raises ValueError:
 
         * If a keyword's value is invalid (e.g. if a ``salt`` string
           is too small, or a ``rounds`` value is out of range).
 
-        * If the *secret* contains characters forbidden by the handler
+        * If the ``secret`` contains characters forbidden by the handler
           (e.g. :class:`!des_crypt` forbids NULL characters).
 
     :raises TypeError:
 
-        * if :samp:`{secret}` is not unicode or bytes.
+        * if ``secret`` is not unicode or bytes.
         * if a keyword argument had an incorrect type.
         * if a required keyword was not provided.
 
+    *(Note that the name of this method is a misnomer, password hashes
+    are typically based on irreversible cryptographic operations,
+    see* :issue:`21` *).*
+
     .. versionchanged:: 1.6
         Hashes now raise :exc:`TypeError` if a required keyword is missing,
         rather than :exc:`ValueError` like in previous releases; in order
@@ -187,7 +197,8 @@ and hash comparison.
     .. versionchanged:: 1.6
         Passlib is now much stricter about input validation: for example,
         out-of-range ``rounds`` values now cause an error instead of being
-        clipped (though applications may set ``relaxed=True`` to restore the old behavior).
+        clipped (though applications may set :ref:`relaxed=True <relaxed-keyword>`
+        to restore the old behavior).
 
 .. classmethod:: PasswordHash.verify(secret, hash, \*\*context_kwds)
 
@@ -202,7 +213,8 @@ and hash comparison.
 
     :type secret: unicode or bytes
     :param hash:
-        A string containing the hash to check against.
+        A string containing the hash to check against,
+        such as returned by :meth:`~encrypt`.
 
         Hashes may be specified as :class:`!unicode` or
         ``ascii``-encoded :class:`!bytes`.
@@ -266,6 +278,8 @@ and hash comparison.
 
 .. _crypt-methods:
 
+.. rst-class:: html-toggle
+
 Crypt Methods
 =============
 Taken together, the :meth:`~PasswordHash.genconfig` and :meth:`~PasswordHash.genhash`
@@ -500,6 +514,8 @@ the hashes in passlib:
 
     .. index:: 
         single: relaxed; PasswordHash keyword
+        
+    .. _relaxed-keyword:
 
     ``relaxed``
         By default, passing :meth:`~PasswordHash.encrypt` an invalid
diff --git a/passlib/utils/des.py b/passlib/utils/des.py
index f21de4d..0422197 100644
--- a/passlib/utils/des.py
+++ b/passlib/utils/des.py
@@ -622,11 +622,11 @@ def expand_des_key(key):
     else:
         raise exc.ExpectedTypeError(key, "bytes or int", "key")
     key = _unpack56(key)
-    # NOTE: this function would insert correctly-valued parity bits in each key,
+    # NOTE: the following would insert correctly-valued parity bits in each key,
     # but the parity bit would just be ignored in des_encrypt_block(),
     # so not bothering to use it.
     ##return join_byte_values(expand_7bit((key >> shift) & 0x7f)
-    #                         for shift in _EXPAND_ITER)
+    ##                        for shift in _EXPAND_ITER)
     return join_byte_values(((key>>shift) & 0x7f)<<1 for shift in _EXPAND_ITER)
 
 def shrink_des_key(key):