docs/uhashlib: Provide port-neutral description.

pfalcon · pfalcon · commit e2f1a8a7ee7b · 2017-02-26T00:55:33.000+03:00
TODO: Remove WiPy-specific chunks.
diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst
@@ -1,33 +1,41 @@
-:mod:`uhashlib` -- hashing algorithm
-====================================
+:mod:`uhashlib` -- hashing algorithms
+=====================================
 
 .. module:: uhashlib
-   :synopsis: hashing algorithm
+   :synopsis: hashing algorithms
 
-.. only:: port_pyboard
+This module implements binary data hashing algorithms. The exact inventory
+of available algorithms depends on a board. Among the algorithms which may
+be implemented:
 
-    This module implements binary data hashing algorithms. Currently, it
-    implements SHA256 algorithm. Choosing SHA256 was a deliberate choice,
-    as a modern, cryptographically secure algorithm. This means that a
-    single algorithm can cover both use cases of "any hash algorithm" and
-    security-related usage, and thus save space omitting legacy algorithms
-    like MD5 or SHA1.
+* SHA256 - The current generation, modern hashing algorithm (of SHA2 series).
+  It is suitable for cryptographically-secure purposes. Included in the
+  MicroPython core and any board is recommended to provide this, unless
+  it has particular code size constraints.
 
-.. only:: port_wipy
-
-    This module implements binary data hashing algorithms. Currently, it
-    implements SHA1 and SHA256 algorithms only. These two algorithms are
-    more than enough for today's web applications.
+* SHA1 - A previous generation algorithm. Not recommended for new usages,
+  but SHA1 is a part of number of Internet standards and existing
+  applications, so boards targetting network connectivity and
+  interoperatiability will try to provide this.
 
+* MD5 - A legacy algorithm, not considered cryptographically secure. Only
+  selected boards, targetting interoperatibility with legacy applications,
+  will offer this.
 
 Constructors
 ------------
 
-.. only:: port_pyboard
+.. class:: uhashlib.sha256([data])
 
-    .. class:: uhashlib.sha256([data])
-    
-       Create a hasher object and optionally feed ``data`` into it.
+    Create an SHA256 hasher object and optionally feed ``data`` into it.
+
+.. class:: uhashlib.sha1([data])
+
+    Create an SHA1 hasher object and optionally feed ``data`` into it.
+
+.. class:: uhashlib.md5([data])
+
+    Create an MD5 hasher object and optionally feed ``data`` into it.
 
 .. only:: port_wipy
 
@@ -69,11 +77,7 @@ Methods
 .. method:: hash.digest()
 
    Return hash for all data passed through hash, as a bytes object. After this
-   method is called, more data cannot be fed into hash any longer.
-
-   .. only:: port_wipy
-   
-        SHA1 hashes are 20-byte long. SHA256 hashes are 32-byte long.
+   method is called, more data cannot be fed into the hash any longer.
 
 .. method:: hash.hexdigest()
 
