Better docs

AUTHORS.rst

@@ -24,7 +24,10 @@ The `BLAKE2 <https://blake2.net>_` code in ``src/blake2/`` is copyright (c) Samu
 
 The authors of Argon2 also were very helpful to get the library to compile on ancient versions of Visual Studio for ancient versions of Python.
 
+The documentation also quotes frequently from the Argon2 paper_ to avoid mistakes by rephrasing.
+
 .. _CC0: https://creativecommons.org/publicdomain/zero/1.0/
+.. _paper: https://password-hashing.net/argon2-specs.pdf
 
 msinttypes
 ^^^^^^^^^^

README.rst

@@ -35,7 +35,7 @@ CFFI-based Argon2 Bindings for Python
     ...
   argon2.exceptions.VerificationError: Decoding failed
 
-You can omit the ``salt`` argument for a secure random salt of length ``argon2.DEFAULT_RANDOM_SALT_LENGTH``:
+You can omit the ``salt`` argument for a secure random `salt <https://en.wikipedia.org/wiki/Salt_(cryptography)>`_ of length ``argon2.DEFAULT_RANDOM_SALT_LENGTH``:
 
 .. code-block:: pycon
 

docs/api.rst

@@ -30,3 +30,6 @@ The raw hash can also be computed:
 
   >>> argon2.hash_password_raw(b"secret", b"somesalt")
   b'\xd8\x87h5X%U<[\xf7\x0e\x18T\x9a\x96\xf3'
+
+.. autoclass:: Type
+  :members: D, I

docs/argon2.rst

@@ -11,8 +11,13 @@ It is designed to have both a configurable runtime as well as memory consumption
 This means that you can decide how long it takes to hash a password and how much memory is required.
 
 Argon2 comes in two variants:
-Argon2\ **d** is faster and uses data-depending memory access, which makes it suitable for cryptocurrencies and applications with no threats from side-channel timing attacks.
-Argon2\ **i** uses data-independent memory access, which is preferred for password hashing and password-based key derivation. Argon2i is slower as it makes more passes over the memory to protect from tradeoff attacks.
+
+Argon2d
+  is faster and uses data-depending memory access, which makes it suitable for cryptocurrencies and applications with no threats from side-channel timing attacks.
+
+Argon2i
+  uses data-independent memory access, which is preferred for password hashing and password-based key derivation.
+  Argon2i is slower as it makes more passes over the memory to protect from tradeoff attacks.
 
 
 Why “just use bcrypt” Is Not the Answer

docs/installation.rst

@@ -1,6 +1,38 @@
 Installation
 ============
 
-A working C compiler is required because the official Argon2 C implementation is shipped along with the Python CFFI bindings.
-Otherwise a plain ``pip install argon2_cffi`` should just work.
-Binary `wheels <http://pythonwheels.com>`_ are offered for OS X and Windows.
+Generally speaking,
+
+.. code-block:: bash
+
+  pip install argon2_cffi
+
+should be all it takes.
+
+But since Argon2 isn't packaged on any major distribution yet, ``argon2_cffi`` vendors its C code which depending on the platform leads to complications.
+
+
+Linux
+-----
+
+A working C compiler is required.
+If you've been able to compile Python CFFI extensions before, ``argon2_cffi`` should install without any problems.
+
+If something goes wrong, please try to update your ``pip`` and ``setuptools`` first:
+
+.. code-block:: bash
+
+  pip install -U pip setuptools
+
+
+Also please note CFFI's dependencies_.
+
+
+OS X & Windows
+--------------
+
+Binary `wheels <http://pythonwheels.com>`_ are provided on PyPI_.
+With a recent-enough ``pip`` and ``setuptools``, they should be used automatically.
+
+.. _PyPI: https://pypi.python.org/pypi/argon2_cffi/
+.. _dependencies: https://cffi.readthedocs.org/en/latest/installation.html#platform-specific-instructions

docs/parameters.rst

@@ -4,7 +4,6 @@ Choosing Parameters
 Finding the right parameters for a password hashing algorithm is a daunting task.
 The authors of Argon2 specified a method in their `paper <https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf>`_ but it should be noted that they also  mention that no value for ``time_cost`` or ``memory_cost`` is actually insecure (cf. section 6.4).
 
-
 #. Choose whether you want Argon2i or Argon2d (``type``).
    If you don't know what that means, choose Argon2i (``Type.I``).
 #. Figure out how many threads can be used on each call to Argon2 (``parallelism``).
@@ -19,3 +18,5 @@ The authors of Argon2 specified a method in their `paper <https://github.com/P-H
 #. Measure the time for hashing using your chosen parameters.
    Find a ``time_cost`` that is within your accounted time.
    If ``time_cost=1`` takes too long, lower ``memory_cost``.
+
+`argon2_cffi`'s :doc:`cli` will help you with this process.

src/argon2/_api.py

@@ -32,7 +32,25 @@ def hash_password(password, salt=None,
                   hash_len=DEFAULT_HASH_LENGTH,
                   type=Type.I):
     """
-    Hash *password* and return an *encoded* hash.
+    Hash *password* and return an **encoded** hash.
+
+    :param bytes password: Password to hash.
+    :param bytes salt: A salt_.  Should be random and different for each
+        password.  Will generate a random salt for you if left ``None``
+        (recommended).
+    :param int time_cost: Defines the amount of computation realized and
+        therefore the execution time, given in number of iterations.
+    :param int memory_cost: Defines the memory usage, given in kibibytes_.
+    :param int parallelism: Defines the number of parallel threads (*changes*
+        the resulting hash value).
+    :param int hash_len: Length of the hash in bytes.
+    :param Type type: Which Argon2 variant to use.  In doubt use the default
+        :attr:`Type.I` which is better suited for passwords.
+
+    :rtype: bytes
+
+    .. _salt: https://en.wikipedia.org/wiki/Salt_(cryptography)
+    .. _kibibytes: https://en.wikipedia.org/wiki/Binary_prefix#kibi
     """
     return _hash(password, salt, time_cost, memory_cost, parallelism, hash_len,
                  type, True)
@@ -45,7 +63,7 @@ def hash_password_raw(password, salt=None,
                       hash_len=DEFAULT_HASH_LENGTH,
                       type=Type.I):
     """
-    Hash *password* and return a *raw* hash.
+    Hash *password* and return a **raw** hash.
 
     The function takes the same parameters as :func:`hash_password`.
     """

src/argon2/_util.py

@@ -11,8 +11,21 @@
 
 
 class Type(Enum):
+    """
+    Enum of Argon2 variants.
+    """
     D = lib.Argon2_d
+    """
+    Argon2\ **d** is faster and uses data-depending memory access, which makes
+    it suitable for cryptocurrencies and applications with no threats from
+    side-channel timing attacks.
+    """
     I = lib.Argon2_i
+    """
+    Argon2\ **i** uses data-independent memory access, which is preferred for
+    password hashing and password-based key derivation.  Argon2i is slower as
+    it makes more passes over the memory to protect from tradeoff attacks.
+    """
 
 
 NoneType = type(None)