Add example, polish docs

README.rst

@@ -43,6 +43,8 @@ CFFI-based Argon2 Bindings for Python
   '$argon2id$v=19$m=102400,t=2,p=8$tSm+JOWigOgPZx/g44K5fQ$WDyus6py50bVFIPkjA28lQ'
   >>> ph.verify(hash, "s3kr3tp4ssw0rd")
   True
+  >>> ph.check_needs_rehash(hash)
+  False
   >>> ph.verify(hash, "t0t411ywr0ng")
   Traceback (most recent call last):
     ...

docs/api.rst

@@ -16,14 +16,22 @@ Unless you have any special needs, all you need to know is:
   '$argon2id$v=19$m=102400,t=2,p=8$tSm+JOWigOgPZx/g44K5fQ$WDyus6py50bVFIPkjA28lQ'
   >>> ph.verify(hash, "s3kr3tp4ssw0rd")
   True
+  >>> ph.check_needs_rehash(hash)
+  False
   >>> ph.verify(hash, "t0t411ywr0ng")
   Traceback (most recent call last):
     ...
   argon2.exceptions.VerifyMismatchError: The password does not match the supplied hash
-  >>> ph.check_needs_rehash(hash)
-  False
 
-But of course the :class:`PasswordHasher` class has all the parametrization you'll need:
+
+A login function could thus look like this:
+
+.. literalinclude:: login_example.py
+   :language: python
+
+----
+
+While the :class:`PasswordHasher` class has the aspiration to be good to use out of the box, it has all the parametrization you'll need:
 
 .. autoclass:: PasswordHasher
   :members: hash, verify, check_needs_rehash

docs/login_example.py

@@ -0,0 +1,17 @@
+import argon2
+
+
+ph = argon2.PasswordHasher()
+
+
+def login(db, user, password):
+    hash = db.get_password_hash_for_user(user)
+
+    # Verify password, raises exception if wrong.
+    ph.verify(hash, password)
+
+    # Now that we have the cleartext password,
+    # check the hash's parameters and if outdated,
+    # rehash the user's password in the database.
+    if ph.check_needs_rehash(hash):
+        db.set_password_hash_for_user(user, ph.hash(password))

src/argon2/_password_hasher.py

@@ -182,11 +182,11 @@ class PasswordHasher(object):
         Whenever your Argon2 parameters -- or ``argon2_cffi``'s defaults! --
         change, you should rehash your passwords at the next opportunity.  The
         common approach is to do that whenever a user logs in, since that
-        should be the only time when you have access to the clear text
+        should be the only time when you have access to the cleartext
         password.
 
         Therefore it's best practice to check -- and if necessary rehash --
-        passwords after each successful authenticaion.
+        passwords after each successful authentication.
 
         :rtype: bool
 

src/argon2/_utils.py

@@ -67,8 +67,8 @@ class Parameters(object):
     :ivar int version: Argon2 version.
     :ivar int salt_len: Length of the salt in bytes.
     :ivar int hash_len: Length of the hash in bytes.
-    :ivar int time_cost: Time cost.
-    :ivar int memory_cost: Memory cost.
+    :ivar int time_cost: Time cost in iterations.
+    :ivar int memory_cost: Memory cost in kibibytes.
     :ivar int parallelism: Number of parallel threads.
 
     .. versionadded:: 18.2.0