traditional post-release tweaks to documentation

5 files changed, 68 insertions, 11 deletions

diff --git a/docs/install.rst b/docs/install.rst
index 4d13b9d..57e39ab 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -16,6 +16,8 @@ Passlib should work with all operating systems,
 as it contains builtin fallbacks
 for almost all OS-dependant features.
 
+.. _optional-libraries: 
+
 Optional Libraries
 ==================
 * `py-bcrypt <http://www.mindrot.org/projects/py-bcrypt/>`_ or
@@ -25,7 +27,7 @@ Optional Libraries
    support for the BCrypt hash algorithm.
    This is required if you want to handle BCrypt hashes,
    and your OS does not provide native BCrypt support
-   via stdlib's :mod:`!crypt` (this is pretty much all non-BSD systems).
+   via stdlib's :mod:`!crypt` (which includes pretty much all non-BSD systems).
 
 * `M2Crypto <http://chandlerproject.org/bin/view/Projects/MeTooCrypto>`_
 
diff --git a/docs/lib/passlib.hash.bcrypt.rst b/docs/lib/passlib.hash.bcrypt.rst
index ccc7c7b..2b9a22d 100644
--- a/docs/lib/passlib.hash.bcrypt.rst
+++ b/docs/lib/passlib.hash.bcrypt.rst
@@ -8,18 +8,43 @@ BCrypt was developed to replace :class:`~passlib.hash.md5_crypt` for BSD systems
 It uses a modified version of the Blowfish stream cipher. Featuring
 a large salt and variable number of rounds, it's currently the default
 password hash for many systems (notably BSD), and has no known weaknesses.
+It is one of the three hashes Passlib :ref:`recommends <recommended-hashes>`
+for new applications.
 
 .. note::
 
-    It is strongly recommended to install PyBcrypt or BCryptor if this algorithm
-    is going to be used.
+    It is strongly recommended to install
+    :ref:`PyBcrypt or BCryptor <optional-libraries>`
+    if this algorithm is going to be used.
 
 Usage
 =====
-
-.. todo::
-
-    write usage instructions
+This class can be used directly as follows::
+
+    >>> from passlib.hash import bcrypt
+
+    >>> #generate new salt, encrypt password
+    >>> h = bcrypt.encrypt("password")
+    >>> h
+    '$2a$12$NT0I31Sa7ihGEWpka9ASYrEFkhuTNeBQ2xfZskIiiJeyFXhRgS.Sy'
+
+    >>> #same, but with explict number of rounds
+    >>> bcrypt.encrypt("password", rounds=8)
+    '$2a$08$8wmNsdCH.M21f.LSBSnYjQrZ9l1EmtBc9uNPGL.9l75YE8D8FlnZC'
+
+    >>> #check if hash is a bcrypt hash
+    >>> bcrypt.identify(h)
+    True
+    >>> #check if some other hash is recognized
+    >>> bcrypt.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31')
+    False
+
+    >>> #verify correct password
+    >>> bcrypt.verify("password", h)
+    True
+    >>> #verify incorrect password
+    >>> bcrypt.verify("wrong", h)
+    False
 
 Interface
 =========
diff --git a/docs/lib/passlib.hash.pbkdf2_digest.rst b/docs/lib/passlib.hash.pbkdf2_digest.rst
index 0f2b1c6..6cd3ea6 100644
--- a/docs/lib/passlib.hash.pbkdf2_digest.rst
+++ b/docs/lib/passlib.hash.pbkdf2_digest.rst
@@ -17,6 +17,8 @@ Though the original PBKDF2 specification uses the SHA-1 message digest,
 it is not vulnerable to any of the known weaknesses of SHA-1 [#hmac-sha1]_,
 and can be safely used. However, for those still concerned, SHA-256 and SHA-512
 versions are offered as well.
+PBKDF2-SHA512 is one of the three hashes Passlib
+:ref:`recommends <recommended-hashes>` for new applications.
 
 .. seealso::
 
@@ -24,9 +26,32 @@ versions are offered as well.
 
 Usage
 =====
-These classes support both rounds and salts,
-and can be used in the exact same manner
-as :doc:`SHA-512 Crypt <passlib.hash.sha512_crypt>`.
+All of the following classes can be used directly as follows::
+
+    >>> from passlib.hash import pbkdf2_sha256 as engine
+
+    >>> #generate new salt, encrypt password
+    >>> hash = engine.encrypt("password")
+    >>> hash
+    '$pbkdf2-sha256$6400$0ZrzXitFSGltTQnBWOsdAw$Y11AchqV4b0sUisdZd0Xr97KWoymNE0LNNrnEgY4H9M'
+
+    >>> #same, but with explicit number of rounds and salt length
+    >>> engine.encrypt("password", rounds=8000, salt_size=10) 
+    '$pbkdf2-sha256$8000$XAuBMIYQQogxRg$tRRlz8hYn63B9LYiCd6PRo6FMiunY9ozmMMI3srxeRE'
+
+    >>> #check if hash is a pbkdf2-sha256 hash
+    >>> engine.identify(hash)
+    True
+    >>> #check if some other hash is recognized
+    >>> engine.identify('$1$3azHgidD$SrJPt7B.9rekpmwJwtON31')
+    False
+
+    >>> #verify correct password
+    >>> engine.verify("password", hash)
+    True
+    >>> #verify incorrect password
+    >>> engine.verify("wrong", hash)
+    False
 
 Interface
 =========
diff --git a/docs/lib/passlib.hash.sha512_crypt.rst b/docs/lib/passlib.hash.sha512_crypt.rst
index db727c9..d9aa1ea 100644
--- a/docs/lib/passlib.hash.sha512_crypt.rst
+++ b/docs/lib/passlib.hash.sha512_crypt.rst
@@ -9,6 +9,8 @@ as a successor to :class:`~passlib.hash.md5_crypt`. They include fixes
 and advancements such as variable rounds, and use of NIST-approved cryptographic primitives.
 SHA-256 / SHA-512 Crypt are currently the default password hash for many systems
 (notably Linux), and have no known weaknesses.
+SHA-512 Crypt is one of the three hashes Passlib :ref:`recommends <recommended-hashes>`
+for new applications.
 
 Usage
 =====
diff --git a/docs/new_app_quickstart.rst b/docs/new_app_quickstart.rst
index ca31f11..a3a84ff 100644
--- a/docs/new_app_quickstart.rst
+++ b/docs/new_app_quickstart.rst
@@ -35,6 +35,8 @@ For applications which started using this preset, but whose needs
 have grown beyond it, it is recommended to create your own :mod:`CryptContext <passlib.context>`
 instance; see below for more...
 
+.. _recommended-hashes:
+
 Choosing a Hash
 ================
 *If you already know what hash algorithm(s) you want to use,
@@ -93,7 +95,8 @@ of simultaneous logon attempts (eg web apps).
 
     For BCrypt support on non-BSD systems,
     Passlib requires a C-extension module
-    provided by the external pybcrypt or bcryptor packages.
+    provided by the external
+    :ref:`PyBcrypt or BCryptor <optional-libraries>`  packages.
     Neither of these currently supports Python 3.
 
 SHA512-Crypt