docs / sha crypt: commented out the "implicit_rounds" param in docs,

it's not actually supported by using(), and isn't needed for users
(issue 121)

2 files changed, 33 insertions, 19 deletions

diff --git a/docs/lib/passlib.hash.sha256_crypt.rst b/docs/lib/passlib.hash.sha256_crypt.rst
index 907ce7a..8d3e950 100644
--- a/docs/lib/passlib.hash.sha256_crypt.rst
+++ b/docs/lib/passlib.hash.sha256_crypt.rst
@@ -70,9 +70,9 @@ An sha256-crypt hash string has the format :samp:`$5$rounds={rounds}${salt}${che
 * :samp:`{checksum}` is 43 characters drawn from the same set, encoding a 256-bit
   checksum (``cKhJImk5mfuSKV9b3mumNzlbstFUplKtQXXMo4G6Ep5`` in the example).
 
-There is also an alternate format :samp:`$5${salt}${checksum}`,
-which can be used when the rounds parameter is equal to 5000
-(see the ``implicit_rounds`` parameter above).
+The official implementation allows omitting the ``rounds`` section when it's set to 5000,
+resulting in an alternate hash format: :samp:`$5${salt}${checksum}`.
+(Passlib supports this via the ``implicit_rounds`` constructor parameter).
 
 The algorithm used by SHA256-Crypt is laid out in detail
 in the specification document linked to below [#f1]_.
diff --git a/passlib/handlers/sha2_crypt.py b/passlib/handlers/sha2_crypt.py
index 6223616..e6060c5 100644
--- a/passlib/handlers/sha2_crypt.py
+++ b/passlib/handlers/sha2_crypt.py
@@ -414,14 +414,9 @@ class sha256_crypt(_SHA2_Common):
         Optional number of rounds to use.
         Defaults to 535000, must be between 1000 and 999999999, inclusive.
 
-    :type implicit_rounds: bool
-    :param implicit_rounds:
-        this is an internal option which generally doesn't need to be touched.
-
-        this flag determines whether the hash should omit the rounds parameter
-        when encoding it to a string; this is only permitted by the spec for rounds=5000,
-        and the flag is ignored otherwise. the spec requires the two different
-        encodings be preserved as they are, instead of normalizing them.
+        .. note::
+            per the official specification, when the rounds parameter is set to 5000,
+            it may be omitted from the hash string.
 
     :type relaxed: bool
     :param relaxed:
@@ -432,6 +427,18 @@ class sha256_crypt(_SHA2_Common):
         that are too small or too large, and ``salt`` strings that are too long.
 
         .. versionadded:: 1.6
+
+    ..
+        commented out, currently only supported by :meth:`hash`, and not via :meth:`using`:
+
+        :type implicit_rounds: bool
+        :param implicit_rounds:
+            this is an internal option which generally doesn't need to be touched.
+
+            this flag determines whether the hash should omit the rounds parameter
+            when encoding it to a string; this is only permitted by the spec for rounds=5000,
+            and the flag is ignored otherwise. the spec requires the two different
+            encodings be preserved as they are, instead of normalizing them.
     """
     #===================================================================
     # class attrs
@@ -473,14 +480,9 @@ class sha512_crypt(_SHA2_Common):
         Optional number of rounds to use.
         Defaults to 656000, must be between 1000 and 999999999, inclusive.
 
-    :type implicit_rounds: bool
-    :param implicit_rounds:
-        this is an internal option which generally doesn't need to be touched.
-
-        this flag determines whether the hash should omit the rounds parameter
-        when encoding it to a string; this is only permitted by the spec for rounds=5000,
-        and the flag is ignored otherwise. the spec requires the two different
-        encodings be preserved as they are, instead of normalizing them.
+        .. note::
+            per the official specification, when the rounds parameter is set to 5000,
+            it may be omitted from the hash string.
 
     :type relaxed: bool
     :param relaxed:
@@ -491,6 +493,18 @@ class sha512_crypt(_SHA2_Common):
         that are too small or too large, and ``salt`` strings that are too long.
 
         .. versionadded:: 1.6
+
+    ..
+        commented out, currently only supported by :meth:`hash`, and not via :meth:`using`:
+
+        :type implicit_rounds: bool
+        :param implicit_rounds:
+            this is an internal option which generally doesn't need to be touched.
+
+            this flag determines whether the hash should omit the rounds parameter
+            when encoding it to a string; this is only permitted by the spec for rounds=5000,
+            and the flag is ignored otherwise. the spec requires the two different
+            encodings be preserved as they are, instead of normalizing them.
     """
 
     #===================================================================