docs: tweaked changelog content, pwd docstrings, added recent setup fix to changelog

2 files changed, 44 insertions, 30 deletions

diff --git a/docs/history/1.7.rst b/docs/history/1.7.rst
index 9f8f735..d84a590 100644
--- a/docs/history/1.7.rst
+++ b/docs/history/1.7.rst
@@ -11,6 +11,8 @@ Passlib 1.7
   keywords.  This usage was deprecated in 1.7.0, but warning wasn't properly enabled.
   See :ref:`hash-configuring` for the preferred way to pass settings.
 
+* bugfix: setup.py: prevent erroneous version strings when run from an sdist.
+
 .. _whats-new:
 
 .. rst-class:: emphasize-children toc-always-open
@@ -179,7 +181,8 @@ Deprecations
 As part of a long-range plan to restructure and simplify both the API and the internals of Passlib,
 a number of methods have been deprecated & replaced.  The eventually goal is a large cleanup
 and overhaul as part of Passlib 2.0. There will be at least one more 1.x version
-before Passlib 2.0, to provide a final transitional release.
+before Passlib 2.0, to provide a final transitional release
+(see the `Passlib Roadmap <https://bitbucket.org/ecollins/passlib/wiki/Roadmap>`_).
 
 Password Hash API Deprecations
 ..............................
@@ -205,11 +208,12 @@ Password Hash API Deprecations
       To provide settings such as ``rounds`` and ``salt_size``, callers
       should use the new :meth:`PasswordHash.using`
       method, which generates a new hasher with a customized configuration.
+      For example, instead of::
 
-        >>>  # for example, instead of this:
         >>>  sha256_crypt.encrypt("secret", rounds=12345)
 
-        >>>  # callers should now use:
+      ... applications should now use::
+
         >>>  sha256_crypt.using(rounds=12345).hash("secret")
 
       Support for the old syntax will be removed in Passlib 2.0.
diff --git a/passlib/pwd.py b/passlib/pwd.py
index 274666a..52e1e64 100644
--- a/passlib/pwd.py
+++ b/passlib/pwd.py
@@ -26,6 +26,7 @@ __all__ = [
 # constants
 #=============================================================================
 
+# XXX: rename / publically document this map?
 entropy_aliases = dict(
     # barest protection from throttled online attack
     unsafe=12,
@@ -435,21 +436,24 @@ def genword(entropy=None, length=None, returns=None, **kwds):
         '310f1a7ac793f'
 
     :param entropy:
-        Strength of resulting password, measured in bits of Shannon entropy
-        (defaults to 48).  An appropriate **length** value will be calculated
+        Strength of resulting password, measured in 'guessing entropy' bits.
+        An appropriate **length** value will be calculated
         based on the requested entropy amount, and the size of the character set.
 
-        If both ``entropy`` and ``length`` are specified,
-        the stronger value will be used.
-
-        This can also be one of a handful of aliases to predefined
-        entropy amounts: ``"weak"`` (24), ``"fair"`` (36),
+        This can be a positive integer, or one of the following preset
+        strings: ``"weak"`` (24), ``"fair"`` (36),
         ``"strong"`` (48), and ``"secure"`` (56).
 
+        If neither this or **length** is specified, **entropy** will default
+        to ``"strong"`` (48).
+
     :param length:
         Size of resulting password, measured in characters.
         If omitted, the size is auto-calculated based on the **entropy** parameter.
 
+        If both **entropy** and **length** are specified,
+        the stronger value will be used.
+
     :param returns:
         Controls what this function returns:
 
@@ -457,9 +461,15 @@ def genword(entropy=None, length=None, returns=None, **kwds):
         * If an integer, this function will return a list containing that many passwords.
         * If the ``iter`` constant, will return an iterator that yields passwords.
 
+    :param chars:
+
+        Optionally specify custom string of characters to use when randomly
+        generating a password. This option cannot be combined with **charset**.
+
     :param charset:
-        The character set to draw from, if not specified explicitly by **chars**.
-        Can be any of:
+
+        The predefined character set to draw from (if not specified by **chars**).
+        There are currently four presets available:
 
         * ``"ascii_62"`` (the default) -- all digits and ascii upper & lowercase letters.
           Provides ~5.95 entropy per character.
@@ -472,11 +482,6 @@ def genword(entropy=None, length=None, returns=None, **kwds):
 
         * ``"hex"`` -- Lower case hexadecimal.  Providers 4 bits of entropy per character.
 
-    :param chars:
-
-        Optionally specify custom charset as a string of characters.
-        This option cannot be combined with **charset**.
-
     :returns:
         :class:`!unicode` string containing randomly generated password;
         or list of 1+ passwords if :samp:`returns={int}` is specified.
@@ -698,21 +703,24 @@ def genphrase(entropy=None, length=None, returns=None, **kwds):
         'wheat dilemma reward rescue diary'
 
     :param entropy:
-        Strength of resulting password, measured in bits of Shannon entropy
-        (defaults to 48).  An appropriate **length** value will be calculated
-        based on the requested entropy amount, and the size of the character set.
+        Strength of resulting password, measured in 'guessing entropy' bits.
+        An appropriate **length** value will be calculated
+        based on the requested entropy amount, and the size of the word set.
 
-        If both ``entropy`` and ``length`` are specified,
-        the stronger value will be used.
-
-        This can also be one of a handful of aliases to predefined
-        entropy amounts: ``"weak"`` (24), ``"fair"`` (36),
+        This can be a positive integer, or one of the following preset
+        strings: ``"weak"`` (24), ``"fair"`` (36),
         ``"strong"`` (48), and ``"secure"`` (56).
 
+        If neither this or **length** is specified, **entropy** will default
+        to ``"strong"`` (48).
+
     :param length:
         Length of resulting password, measured in words.
         If omitted, the size is auto-calculated based on the **entropy** parameter.
 
+        If both **entropy** and **length** are specified,
+        the stronger value will be used.
+
     :param returns:
         Controls what this function returns:
 
@@ -720,8 +728,14 @@ def genphrase(entropy=None, length=None, returns=None, **kwds):
         * If an integer, this function will return a list containing that many passwords.
         * If the ``iter`` builtin, will return an iterator that yields passwords.
 
+    :param words:
+
+        Optionally specifies a list/set of words to use when randomly generating a passphrase.
+        This option cannot be combined with **wordset**.
+
     :param wordset:
-        Optionally use a pre-defined word-set when generating a passphrase.
+
+        The predefined word set to draw from (if not specified by **words**).
         There are currently four presets available:
 
         ``"eff_long"`` (the default)
@@ -756,10 +770,6 @@ def genphrase(entropy=None, length=None, returns=None, **kwds):
             (at the cost of slightly less entropy); and much shorter than
             ``"eff_prefixed"`` (at the cost of a longer unique prefix).
 
-    :param words:
-        Optionally specifies a list/set of words to use when randomly generating a passphrase.
-        This option cannot be combined with **wordset**.
-
     :param sep:
         Optional separator to use when joining words.
         Defaults to ``" "`` (a space), but can be an empty string, a hyphen, etc.