3 files changed, 61 insertions, 9 deletions
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
 =====