minor documentation updates

6 files changed, 45 insertions, 28 deletions

diff --git a/docs/lib/passlib.hash.bsdi_crypt.rst b/docs/lib/passlib.hash.bsdi_crypt.rst
index bb3aa92..464cd67 100644
--- a/docs/lib/passlib.hash.bsdi_crypt.rst
+++ b/docs/lib/passlib.hash.bsdi_crypt.rst
@@ -40,7 +40,7 @@ Interface
 Format
 ======
 An example hash (of the string ``password``) is ``_EQ0.jzhSVeUyoSqLupI``.
-An ext_des_crypt hash string consists of a 21 character string of the form :samp:`_{rounds}{salt}{checksum}`.
+A bsdi_crypt hash string consists of a 21 character string of the form :samp:`_{rounds}{salt}{checksum}`.
 All characters except the underscore prefix are drawn from ``[./0-9A-Za-z]``.
 
 * ``_`` - the underscore is used to distinguish this scheme from others, such as des-crypt.
@@ -48,7 +48,7 @@ All characters except the underscore prefix are drawn from ``[./0-9A-Za-z]``.
 * :samp:`{salt}` is the salt, stored as as a 4 character hash64-encoded 24-bit integer (``jzhS`` in the example).
 * :samp:`{checksum}` is the checksum, stored as an 11 character hash64-encoded 64-bit integer (``VeUyoSqLupI`` in the example).
 
-A ext_des_crypt configuration string is also accepted by this module;
+A bsdi_crypt configuration string is also accepted by this module;
 and has the same format as the hash string, but with the checksum portion omitted.
 
 .. rst-class:: html-toggle
diff --git a/passlib/context.py b/passlib/context.py
index f27e6c0..f9f2d0c 100644
--- a/passlib/context.py
+++ b/passlib/context.py
@@ -1167,7 +1167,7 @@ class CryptContext(object):
               and the hash does not need upgrading.
             * ``(True, str)`` indicates the secret verified correctly,
               but the existing hash has been deprecated, and should be replaced
-              by the one returned as ``new_hash``.
+              by the :class:`str` returned as ``new_hash``.
 
         .. seealso:: :ref:`context-migrating-passwords` for a usage example.
         """
diff --git a/passlib/handlers/bcrypt.py b/passlib/handlers/bcrypt.py
index e17282c..71218e0 100644
--- a/passlib/handlers/bcrypt.py
+++ b/passlib/handlers/bcrypt.py
@@ -70,14 +70,15 @@ class bcrypt(uh.HasManyIdents, uh.HasRounds, uh.HasSalt, uh.HasManyBackends, uh.
 
     It will use the first available of three possible backends:
 
-    * `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_, if installed.
-    * `bcryptor <https://bitbucket.org/ares/bcryptor/overview>`_, if installed.
-    * stdlib :func:`crypt()`, if the host OS supports BCrypt (eg: BSD).
-    * if no backends are available at runtime,
-      :exc:`~passlib.utils.MissingBackendError` will be raised
-      whenever :meth:`encrypt` or :meth:`verify` are called.
-
-    You can see which backend is in use by calling the :meth:`get_backend()` method.
+    1. `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_, if installed.
+    2. `bcryptor <https://bitbucket.org/ares/bcryptor/overview>`_, if installed.
+    3. stdlib's :func:`crypt.crypt()`, if the host OS supports BCrypt (eg: BSD).
+    
+    If no backends are available at runtime,
+    :exc:`~passlib.utils.MissingBackendError` will be raised
+    whenever :meth:`encrypt` or :meth:`verify` are called.
+    You can see which backend is in use by calling the
+    :meth:`~passlib.utils.handlers.HasManyBackends.get_backend()` method.
     """
 
     #=========================================================
diff --git a/passlib/handlers/phpass.py b/passlib/handlers/phpass.py
index 01e9f8f..f366870 100644
--- a/passlib/handlers/phpass.py
+++ b/passlib/handlers/phpass.py
@@ -3,7 +3,7 @@
 phppass located - http://www.openwall.com/phpass/
 algorithm described - http://www.openwall.com/articles/PHP-Users-Passwords
 
-phpass context - blowfish, ext_des_crypt, phpass
+phpass context - blowfish, bsdi_crypt, phpass
 """
 #=========================================================
 #imports
diff --git a/passlib/utils/h64.py b/passlib/utils/h64.py
index e3f1656..d95f4bc 100644
--- a/passlib/utils/h64.py
+++ b/passlib/utils/h64.py
@@ -128,7 +128,7 @@ def decode_transposed_bytes(source, offsets):
     return belem_join(buf)
 
 #=================================================================================
-# int <-> b64 string, used by des_crypt, ext_des_crypt
+# int <-> b64 string, used by des_crypt, bsdi_crypt
 #=================================================================================
 
 def decode_int6(source):
diff --git a/passlib/utils/handlers.py b/passlib/utils/handlers.py
index 410ffca..0c96b5c 100644
--- a/passlib/utils/handlers.py
+++ b/passlib/utils/handlers.py
@@ -972,31 +972,47 @@ class HasRounds(GenericHandler):
 class HasManyBackends(GenericHandler):
     """GenericHandler mixin which provides selecting from multiple backends.
 
+    .. todo::
+
+        finish documenting this class's usage
+
     For hashes which need to select from multiple backends,
     depending on the host environment, this class
     offers a way to specify alternate :meth:`calc_checksum` methods,
-    will dynamically chose the best one at runtime.
-
-    .. todo::
+    and will dynamically chose the best one at runtime.
 
-        document this class's usage
-
-    .. attribute:: backends
-    
-        tuple containing names of the backends which are supported.
-        two common names are ``"os_crypt"`` (if backend uses :mod:`crypt`),
-        and ``"builtin"`` (if the backend is a pure-python fallback).
+    Backend Methods
+    ---------------
 
     .. automethod:: get_backend
     .. automethod:: set_backend
     .. automethod:: has_backend
 
-    .. attribute:: _has_backend_{xxx}
+    Subclass Hooks
+    --------------
+    The following attributes and methods should be filled in by the subclass
+    which is using :class:`HasManyBackends` as a mixin:
+
+    .. attribute:: backends
+    
+        This attribute should be a tuple containing the names of the backends
+        which are supported. Two common names are ``"os_crypt"`` (if backend
+        uses :mod:`crypt`), and ``"builtin"`` (if the backend is a pure-python
+        fallback). 
 
-        private class attr used by :meth:`has_backend`
-        to check if a specific backend is available.
-        one of these should be provided by subclass 
-        for each backend listed in :attr:`backends`.
+    .. attribute:: _has_backend_{name}
+
+        private class attribute checked by :meth:`has_backend` to see if a
+        specific backend is available, it should be either ``True``
+        or ``False``. One of these should be provided by
+        the subclass for each backend listed in :attr:`backends`.
+        
+    .. classmethod:: _calc_checksum_{name}
+    
+        private class method that should implement :meth:`calc_checksum`
+        for a given backend. it will only be called if the backend has
+        been selected by :meth:`set_backend`. One of these should be provided
+        by the subclass for each backend listed in :attr:`backends`.
     """
 
     #NOTE: subclass must provide: