Better document hash function strings [ci skip]

See #1822

1 files changed, 29 insertions, 3 deletions

diff --git a/doc/manual/hash.rst b/doc/manual/hash.rst
index 517af9f18..5de2d7c5c 100644
--- a/doc/manual/hash.rst
+++ b/doc/manual/hash.rst
@@ -22,6 +22,16 @@ internal state is reset to begin hashing a new message.
 
 .. cpp:class:: HashFunction
 
+  .. cpp:function:: static std::unique_ptr<HashFunction> create(const std::string& name)
+
+    Return a newly allocated hash function object, or nullptr if the
+    name is not recognized.
+
+  .. cpp:function:: static std::unique_ptr<HashFunction> create_or_throw(const std::string& name)
+
+    Like ``create`` except that it will throw an exception instead of
+    returning nullptr.
+
   .. cpp:function:: size_t output_length()
 
     Return the size (in *bytes*) of the output of this function.
@@ -110,6 +120,9 @@ A recently designed hash function. Very fast on 64-bit processors. Can output a
 hash of any length between 1 and 64 bytes, this is specified by passing a value
 to the constructor with the desired length.
 
+Named like "Blake2b" which selects default 512-bit output, or as
+"Blake2b(256)" to select 256 bits of output.
+
 GOST-34.11
 ^^^^^^^^^^^^^^^
 
@@ -182,13 +195,18 @@ Available if ``BOTAN_HAS_SHA3`` is defined.
 
 The new NIST standard hash. Fairly slow.
 
+Supports 224, 256, 384 or 512 bit outputs. SHA-3 is faster with
+smaller outputs.  Use as "SHA-3(256)" or "SHA-3(512)". Plain "SHA-3"
+selects default 512 bit output.
+
 SHAKE (SHAKE-128, SHAKE-256)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Available if ``BOTAN_HAS_SHAKE`` is defined.
 
-These are actually XOFs (extensible output functions) based on SHA-3, which can
-output a value of any length.
+These are actually XOFs (extensible output functions) based on SHA-3,
+which can output a value of any byte length. For example "SHAKE-128(1024)"
+will produce 1024 bits of output.
 
 SM3
 ^^^^^^^^^^^^^^^
@@ -204,10 +222,14 @@ Skein-512
 Available if ``BOTAN_HAS_SKEIN_512`` is defined.
 
 A contender for the NIST SHA-3 competition. Very fast on 64-bit systems.  Can
-output a hash of any length between 1 and 64 bytes. It also accepts a
+output a hash of any length between 1 and 64 bytes. It also accepts an optional
 "personalization string" which can create variants of the hash. This is useful
 for domain separation.
 
+To set a personalization string set the second param to any value,
+typically ASCII strings are used. Examples "Skein-512(256)" or
+"Skein-512(384,personalization_string)".
+
 Streebog (Streebog-256, Streebog-512)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -226,6 +248,10 @@ An older 192-bit hash function, optimized for 64-bit systems. Possibly
 vulnerable to side channels due to its use of table lookups. Prefer Skein-512 or
 BLAKE2b in new code.
 
+Tiger supports variable length output (16, 20 or 24 bytes) and
+variable rounds (which must be at least 3). Default is 24 byte output
+and 3 rounds. Specify with names like "Tiger" or "Tiger(20,5)".
+
 Whirlpool
 ^^^^^^^^^^^^^^^