From: Fabio Scotoni <34964387+fscoto@users.noreply.github.com>
Date: Fri, 20 Jan 2023 18:18:02 +0000 (+0100)
Subject: Normalize crypto_blake2b markup
X-Git-Url: https://git.codecow.com/?a=commitdiff_plain;h=c51e6a44886be12eb061fa792d9477db4971ef7f;p=Monocypher.git

Normalize crypto_blake2b markup

Struct documentation by mdoc(7) convention does not go in the synopsis.
Similarly, external constants are not part of .Nm,
which is only used for the actual function names.

Constants are marked up with .Dv,
whether they are macros or not.
---

diff --git a/doc/man/man3/crypto_blake2b.3monocypher b/doc/man/man3/crypto_blake2b.3monocypher
index cc82e70..ae11756 100644
--- a/doc/man/man3/crypto_blake2b.3monocypher
+++ b/doc/man/man3/crypto_blake2b.3monocypher
@@ -10,7 +10,7 @@
 .\"
 .\" Copyright (c) 2017-2023 Loup Vaillant
 .\" Copyright (c) 2018 Michael Savage
-.\" Copyright (c) 2017, 2020-2022 Fabio Scotoni
+.\" Copyright (c) 2017, 2020-2023 Fabio Scotoni
 .\" All rights reserved.
 .\"
 .\"
@@ -50,7 +50,7 @@
 .\" with this software.  If not, see
 .\" <https://creativecommons.org/publicdomain/zero/1.0/>
 .\"
-.Dd January 13, 2023
+.Dd January 20, 2023
 .Dt CRYPTO_BLAKE2B 3MONOCYPHER
 .Os
 .Sh NAME
@@ -58,21 +58,9 @@
 .Nm crypto_blake2b_init ,
 .Nm crypto_blake2b_update ,
 .Nm crypto_blake2b_final
-.Nm crypto_blake2b_defaults
 .Nd cryptographic hashing
 .Sh SYNOPSIS
 .In monocypher.h
-.Bd -literal -offset
-typedef struct {
-	const uint8_t *key;
-	size_t key_size;
-	size_t hash_size;
-} crypto_blake2b_config;
-.Ed
-.Bd -literal -offset
-extern const crypto_blake2b_config crypto_blake2b_defaults;
-.Ed
-.Pp
 .Ft void
 .Fo crypto_blake2b
 .Fa "uint8_t hash[64]"
@@ -96,6 +84,7 @@ extern const crypto_blake2b_config crypto_blake2b_defaults;
 .Fa "crypto_blake2b_ctx *ctx"
 .Fa "uint8_t *hash"
 .Fc
+.Fa "extern const crypto_blake2b_config crypto_blake2b_defaults;"
 .Sh DESCRIPTION
 BLAKE2b is a fast cryptographically secure hash based on the ideas of
 ChaCha20.
@@ -110,12 +99,46 @@ family of functions for that purpose instead.
 BLAKE2b is immune to length extension attacks, and as such, does not
 require specific precautions such as using the HMAC algorithm.
 .Pp
-The arguments are:
+The arguments to
+.Fn crypto_blake2b
+are:
 .Bl -tag -width Ds
 .It Fa config
-The Configuration parameters, comprising:
+The configuration parameter structure, see below.
+.It Fa hash
+The output hash.
+.It Fa message
+The message to hash.
+May overlap with
+.Fa hash .
+May be
+.Dv NULL
+if
+.Fa message_size
+is 0.
+.It Fa message_size
+Length of
+.Fa message ,
+in bytes.
+.El
+.Pp
+The BLAKE2b hash function has configurable parameters to personalize
+instances.
+These parameters are given in a
+.Vt crypto_blake2b_config
+structure,
+which is defined as follows:
+.Bd -literal -offset Ds
+typedef struct {
+	const uint8_t *key;
+	size_t key_size;
+	size_t hash_size;
+} crypto_blake2b_config;
+.Ed
+.Pp
+Its members are:
 .Bl -tag -width Ds
-.It Fa config.hash_size
+.It Fa hash_size
 Length of
 .Fa hash ,
 in bytes.
@@ -124,13 +147,13 @@ Anything below 32 is discouraged when using BLAKE2b as a general-purpose
 hash function;
 anything below 16 is discouraged when using BLAKE2b as a message
 authentication code.
-.It Fa config.key
+.It Fa key
 Some secret key.
 One cannot predict the final hash without it.
 May be
 .Dv NULL
 if
-.Fa config.key_size
+.Fa key_size
 is 0, in which case no key is used.
 Keys can be used to create a message authentication code (MAC).
 Use
@@ -143,32 +166,16 @@ Choose the size of the hash accordingly.
 Users may want to wipe the key with
 .Xr crypto_wipe 3monocypher
 once they are done with it.
-.It Fa config.key_size
+.It Fa key_size
 Length of
 .Fa key ,
 in bytes.
 Must be between 0 and 64.
 32 is a good default.
 .El
-.It Fa hash
-The output hash.
-.It Fa message
-The message to hash.
-May overlap with
-.Fa hash .
-May be
-.Dv NULL
-if
-.Fa message_size
-is 0.
-.It Fa message_size
-Length of
-.Fa message ,
-in bytes.
-.El
 .Pp
 The
-.Fa crypto_blake2b_defaults
+.Dv crypto_blake2b_defaults
 constant provides default
 .Fa config
 parameters:
@@ -283,8 +290,6 @@ These functions implement BLAKE2b, described in RFC 7693.
 .Sh HISTORY
 The
 .Fn crypto_blake2b ,
-.Fn crypto_blake2b_general ,
-.Fn crypto_blake2b_general_init ,
 .Fn crypto_blake2b_init ,
 .Fn crypto_blake2b_update ,
 and