Man page fixes

Signed-off-by: Mattias Andrée <m@maandree.se>

12 files changed, 114 insertions, 105 deletions

diff --git a/libar2_decode_base64.3 b/libar2_decode_base64.3
index 03cd8b8..159a0ed 100644
--- a/libar2_decode_base64.3
+++ b/libar2_decode_base64.3
@@ -15,7 +15,7 @@ Link with
 .SH DESCRIPTION
 The
 .BR libar2_decode_base64 ()
-function decodes some binary data that has
+function decodes binary data that has
 been encoded with base64. The base64-encoding
 shall be provided via the
 .I str
@@ -32,7 +32,7 @@ is stored in
 .PP
 .I str
 may, but does not have to, be padded, up to
-(or short there of) the next length that is
+(or short thereof) the next length that is
 divisible by 4, unless the length is already
 divisible by 4, using equals-sign
 .RB ( = )
@@ -80,7 +80,7 @@ dynamically allocated buffer.
 #include <stdlib.h>
 
 static char *
-decode_base64(const const *str, char **endp, size_t *lenp)
+decode_base64(const *str, char **endp, size_t *lenp)
 {
     size_t len;
     size_t n = libar2_decode_base64(str, NULL, &len);
diff --git a/libar2_decode_params.3 b/libar2_decode_params.3
index 9bb1427..d533e2a 100644
--- a/libar2_decode_params.3
+++ b/libar2_decode_params.3
@@ -40,8 +40,8 @@ struct libar2_context {
     void (*\fIdeallocate\fP)(void *\fIptr\fP, struct libar2_context *\fIctx\fP);
 };
 
-size_t libar2_decode_params(const char *\fIstr\fP, const struct libar2_argon2_parameters *\fIparams\fP,
-                            char **\fIbuf\fP, struct libar2_context *\fIctx\fP);
+size_t libar2_decode_params(const char *\fIstr\fP, struct libar2_argon2_parameters *\fIparams\fP,
+                            char **\fIbufp\fP, struct libar2_context *\fIctx\fP);
 .fi
 .PP
 Link with
@@ -98,7 +98,7 @@ once, and on failure if
 was called,
 .I *ctx->deallocate
 once. If
-.I *ctx->allocatew
+.I *ctx->allocate
 was called, but not
 .IR *ctx->deallocate ,
 the memory allocated with
@@ -109,8 +109,8 @@ and may be deallocated by the user with
 .I *ctx->deallocate
 once the result stored in
 .I params
-is not longer needed.
-See more information about
+is no longer needed.
+For more information about
 .I ctx->allocate
 and
 .IR ctx->deallocate ,
@@ -124,7 +124,7 @@ None of the arguments may be
 .PP
 Upon successful completion, if
 .I str
-contains the a tag,
+contains a tag,
 .IR &str[n] ,
 where
 .I n
@@ -136,7 +136,7 @@ The
 .BR libar2_decode_params ()
 returns the number of bytes in
 .I str
-that make up the decoded parameter, including
+that make up the decoded parameters, including
 the final dollar-sign
 .RB ( $ ),
 but excluding the tag, if any, at the end of
@@ -145,9 +145,9 @@ and stores the decoded parameters in
 .IR params ,
 and potentially dynamically allocated data in
 .IR *bufp ,
-upon successful completion
+upon successful completion.
 On error, 0 is returned (not a valid return
-value on success completion) and
+value on successful completion) and
 .I errno
 is set to describe the error.
 
@@ -178,7 +178,7 @@ not modify
 
 .SH NOTES
 The encoded parameters will not be
-validate by the
+validated by the
 .BR libar2_decode_params ()
 function beyond what is needed to ensure that
 the parameters can be accurately parsed and
diff --git a/libar2_encode_base64.3 b/libar2_encode_base64.3
index 279f23d..6348c71 100644
--- a/libar2_encode_base64.3
+++ b/libar2_encode_base64.3
@@ -17,8 +17,7 @@ Link with
 .SH DESCRIPTION
 The
 .BR libar2_encode_base64 ()
-function encodes some binary data, provided
-via the
+function encodes binary data provided via the
 .I data
 parameter, into base64, and stores the base64
 encoding in
@@ -52,11 +51,11 @@ is
 .PP
 In previous versions of libar2, the
 .BR libar2_encode_base64 (3)
-did not support overlap in the
+function did not support overlap in the
 .I buf
 and
-.IR data ,
-this was a bug. The existence of the
+.IR data
+parameters; this was a bug. The presence of the
 .B libar2_encode_base64_overlap_support
 macro indicates that this bug has been fixed.
 The
diff --git a/libar2_encode_params.3 b/libar2_encode_params.3
index b0566ff..d901a75 100644
--- a/libar2_encode_params.3
+++ b/libar2_encode_params.3
@@ -44,7 +44,7 @@ The
 .BR libar2_encode_params ()
 function encodes the Argon2 hashing parameters
 provided via the
-.I param
+.I params
 parameter, as a string, in a standardised format,
 and stores the string in
 .I buf
@@ -56,9 +56,9 @@ and return the number of bytes that was (or would
 have been) written to
 .IR buf .
 .PP
-It is recommended that the
+It is recommended to call the
 .BR libar2_encode_params ()
-function is called twice: first with
+function twice: first with
 .I buf
 set to
 .IR NULL ,
@@ -72,7 +72,7 @@ with an allocation size of at least the number
 of bytes that was returned by the function in
 the previous call to it.
 .PP
-The created string will have the following format
+The generated string will have the following format
 
 .RS
 .B \(dq$%s$v=%i$m=%lu,t=%lu,p=%lu$%s$\(dq,
@@ -80,8 +80,8 @@ The created string will have the following format
 .RI < version >\fB,\fP
 .RI < "memory cost" >\fB,\fP
 .RI < "time cost" >\fB,\fP
-.RI < "parallelism" >\fB,\fP
-.RI < "base64 encoded salt" >
+.RI < parallelism >\fB,\fP
+.RI < "base64-encoded salt" >
 .RE
 
 if the version is explicitly specified, and otherwise
@@ -91,8 +91,8 @@ if the version is explicitly specified, and otherwise
 .RI < type >\fB,\fP
 .RI < "memory cost" >\fB,\fP
 .RI < "time cost" >\fB,\fP
-.RI < "parallelism" >\fB,\fP
-.RI < "base64 encoded salt" >
+.RI < parallelism >\fB,\fP
+.RI < "base64-encoded salt" >
 .RE
 
 The string does not encode the \(dqsecret\(dq
@@ -104,11 +104,11 @@ is encoded in base64 and appended to the string
 formatted by this function. For information
 about the expected contents of the
 .I params
-argument, see 
+argument, see
 .BR libar2_hash (3).
 .PP
 .I params
-may not be
+must not be
 .IR NULL .
 
 .SH RETURN VALUES
@@ -138,7 +138,7 @@ function cannot fail.
 
 .SH EXAMPLES
 The following example demonstrates how to
-encode the hashing parameters into a dynamically
+encode hashing parameters into a dynamically
 allocated string.
 .PP
 .nf
@@ -161,7 +161,7 @@ encode_params(const struct libar2_argon2_parameters *params)
 .SH NOTES
 The
 .BR libar2_encode_params ()
-function till note validate its input.
+function will not validate its input.
 This has to be done using the
 .BR libar2_validate_params (3)
 function.
diff --git a/libar2_erase.3 b/libar2_erase.3
index 0d33c50..1360108 100644
--- a/libar2_erase.3
+++ b/libar2_erase.3
@@ -28,7 +28,7 @@ the compiler should not be able to optimise
 away a call to the
 .BR libar2_erase ()
 function, even if link-time optimisation
-is enabled, and is thus recommended for
+is enabled, and it is thus recommended for
 wiping passwords from memory after they
 have been hashed.
 .PP
@@ -51,7 +51,7 @@ function cannot fail.
 Depending on the compiler used to compile
 the library, the
 .BR libar2_erase ()
-may be weakly linked so that it can be
+function may be weakly linked so that it can be
 replaced by the application.
 
 .SH SEE ALSO
diff --git a/libar2_hash.3 b/libar2_hash.3
index 1e7cd2c..85cc979 100644
--- a/libar2_hash.3
+++ b/libar2_hash.3
@@ -106,20 +106,20 @@ and
 shall be set according to the following specifications:
 .TP
 .B params->type
-Argon2 primitiv type. This shall be one of
+Argon2 primitive type. This shall be one of
 the following values:
 .I LIBAR2_ARGON2D
 (secret-depending hashing: only for
 side-channel-free environments),
 .I LIBAR2_ARGON2I
 (secret-independent hashing; good for environments
-with side-channels but worse wit respect to trade
-of attacks if only one pass is used),
+with side-channels but worse with respect to trade
+off attacks if only one pass is used),
 .I LIBAR2_ARGON2ID
 (hybrid construction; OK against side-channels
 and better with respect to tradeoff attacks),
 .I LIBAR2_ARGON2DS
-(substition box (S-box)-hardened construction;
+(substitution box (S-box)-hardened construction;
 .B NB!
 This construction was not included in the
 submission to the Password Hashing Competition).
@@ -128,7 +128,7 @@ submission to the Password Hashing Competition).
 Argon2 version number.
 .I LIBAR2_ARGON2_VERSION_10
 or 0 (implicit specification)
-for verison 1.0 and
+for version 1.0 and
 .I LIBAR2_ARGON2_VERSION_13
 for version 1.3.
 .TP
@@ -147,7 +147,7 @@ address space (that is, the address space
 divided by 2048).
 .TP
 .B params->lanes
-Number of lines, also called the parallelism
+Number of lanes, also called the parallelism
 parameter. Must be a positive (not zero)
 number less than 2 to the power of 24.
 .TP
@@ -173,7 +173,7 @@ is 0.
 .B params->keylen
 The number of bytes stored in
 .IR params->key .
-Must a non-negative integer and less than
+Must be a non-negative integer and less than
 2 to the power of 32.
 .TP
 .B params->ad
@@ -185,7 +185,7 @@ is 0.
 .B params->adlen
 The number of bytes stored in
 .IR params->ad .
-Must a non-negative integer and less than
+Must be a non-negative integer and less than
 2 to the power of 32.
 .TP
 .B params->hashlen
@@ -195,21 +195,21 @@ less than 2 to the power of 32.
 .TP
 .B ctx->user_data
 User-defined data which may be used by
-callbacks functions provided by the application.
+callback functions provided by the application.
 This field is not used by the libar2 library.
 .TP
 .B ctx->autoerase_message
 Whether
 .I msg
 shall be erased when the function no
-longer needs it. (High recommended for if
+longer needs it. (Highly recommended if
 .I msg
 is a password that is only hashed once.)
 Note that there is no guarantee that
 .I msg
-is erased if the function fails
+is erased if the function fails.
 .TP
-.B ctx->autoerase_secret.
+.B ctx->autoerase_secret
 Whether
 .I params->key
 shall be erased when the function no
@@ -243,15 +243,17 @@ The function shall allocate
 .I num
 times
 .I size
-bytes allocated to a multiple of
+bytes aligned to a multiple of
 .I alignment
 bytes, and return a pointer to the allocated
 memory; or return
 .I NULL
 on failure. The
 .I ctx
-parameter will be set to struct containing
-the function pointer. It is guaranteed that
+parameter will be set to the
+.B struct
+containing the function pointer.
+It is guaranteed that
 .IR num ,
 .IR size ,
 and
@@ -277,15 +279,15 @@ and to be allocated using
 .IR *ctx->allocate .
 The
 .I ctx
-parameter will be set to struct containing
-the function pointer.
+parameter will be set to the
+.B struct
+containing the function pointer.
 
 .B NB!
 The
 .BR libar2_hash ()
 function will not write over memory before
-it deallocates it. This can be done function
-within
+it deallocates it. This can be done within
 .IR *ctx->allocate
 using the
 .BR libar2_erase (3)
@@ -304,17 +306,18 @@ will be set to the maximum number of threads the
 function will be using, meaning that the thread
 pool need not contain more than this number of
 threads, but may contain less if it is deemed
-desirable. the
+desirable. The
 .BR libar2_hash ()
-function will not determine what is optimial,
-this is left up to the application to dermine.
+function will not determine what is optimal,
+this is left up to the application to determine.
 The number of created threads shall be stored in
 .IR *createdp .
 The
 .I ctx
-parameter will be set to struct containing
-the function pointer. The function shall return
-0 on success, and -1 on failure.
+parameter will be set to
+.B struct
+containing the function pointer. The function
+shall return 0 on success, and -1 on failure.
 If the function stores 0 in
 .IR *createdp ,
 .IR ctx->get_ready_threads ,
@@ -322,84 +325,90 @@ If the function stores 0 in
 .IR ctx->join_thread_pool ,
 and
 .IR ctx->destroy_thread_pool
-need note be set.
+need not be set.
 .TP
 .B ctx->get_ready_threads
 Pointer to a function that waits until at least one
 thread in the thread pool is ready (may be immediately),
 and stores up to
 .I n
-of their indices (the first thread have index 0) in
+of their indices (the first thread has index 0) in
 .IR indices .
 The function shall return the number of ready threads.
 It is permissible to return a lesser number as long
 as the returned number is positive and does not exceed
-that number of indices stored in
+the number of indices stored in
 .IR indices .
 On failure the function shall return 0. The
 .I ctx
-parameter will be set to struct containing
-the function pointer.
+parameter will be set to the
+.B struct
+containing the function pointer.
 .TP
 .B ctx->run_thread
-Pointer to a function that makes a thread on the
+Pointer to a function that makes a thread in the
 thread pool run the function provided in
 .I function
 with the argument provided in
 .IR data .
 .I index
 will be the index of the thread (the first thread
-have index 0) that shall run the function. It will
+has index 0) that shall run the function. It will
 be guaranteed by
 .I *ctx->get_ready_threads
 that the thread is resting. The
 .I ctx
-parameter will be set to struct containing
-the function pointer.
+parameter will be set to the
+.B struct
+containing the function pointer.
 .TP
 .B ctx->join_thread_pool
 Pointer to a function that waits until all
 threads in the thread pool are resting. The
 .I ctx
-parameter will be set to struct containing
-the function pointer. The function shall return
-0 on successful completion and -1 on failure.
+parameter will be set to the
+.B struct
+containing the function pointer. The function
+shall return 0 on successful completion and
+-1 on failure.
 .TP
 .B ctx->destroy_thread_pool
 Pointer to a function that destroys the
 thread pool, and all threads in it. The
 .I ctx
-parameter will be set to struct containing the
+parameter will be set to the
+.B struct
+containing the
 function pointer, and it will be guaranteed
 that all threads in the thread pool are resting.
 It is guaranteed that the function is called
 if and only if
-.I *ctx->init_thread_poolw
-return 0 and stored a non-0 number in its
+.I *ctx->init_thread_pool
+returned 0 and stored a non-0 number in its
 .IR *createdp ,
 except if
 .I *ctx->join_thread_pool
 or
-.I *ctx->.get_ready_threads
+.I *ctx->get_ready_threads
 failed.
 .PP
 It is safe to assume that
 .I *ctx->allocate
 and
 .I *ctx->deallocate
-are called in stack order and are never
+are called in stack-order and are never
 called from code called using
 .IR *ctx->run_thread ,
 that is, only one thread will be calling
-it from inside the
+them from inside the
 .BR libar2_hash ()
 function.
 .PP
 If thread support is desired, but the application
-do not want to keep track of the threads using a
-thread pool, The
+does not want to keep track of the threads using a
+thread pool, the
 .I *ctx->init_thread_pool
-function must store the provided in its
+function must store the value provided in its
 .I desired
 parameter to its memory location provided in its
 .I createdp
@@ -422,17 +431,17 @@ calculate it with
 Alternatively, and more preferably, this scheme
 can be used, but adapted to limit the number of
 concurrent threads, keeping track of the number
-of running threads, and not let the
+of running threads, and not letting the
 .I *ctx->get_ready_threads
 function return before this number is small
 enough; the value stored in
 .I *createdp
-must however still set to the value provided
+must however still be set to the value provided
 to the
 .I *ctx->init_thread_pool
 function in its
 .I desired
-parametr, so that to threads are not running
+parameter, so that two threads are not running
 concurrently with the same memory segment as the
 provided argument for the function to run, as
 this could be a source of memory corruption. It
@@ -445,8 +454,8 @@ times.
 .SH RETURN VALUES
 The
 .BR libar2_hash ()
-returns 0 and stores the binary hash of the
-message in
+function returns 0 and stores the binary hash
+of the message in
 .I hash
 upon successful completion. On error -1
 is returned and
@@ -469,7 +478,7 @@ is too large.
 .PP
 The
 .BR libar2_hash ()
-function will also fail if the any
+function will also fail if any
 function provided via
 .I ctx
 fails, and will, in that case, not modify
diff --git a/libar2_hash_buf_size.3 b/libar2_hash_buf_size.3
index 6c0d62b..cb768bc 100644
--- a/libar2_hash_buf_size.3
+++ b/libar2_hash_buf_size.3
@@ -18,7 +18,7 @@ The
 function returns the number of bytes that the
 output buffer for the
 .BR libar2_hash (3)
-function must fit (that it, it's first parameter).
+function must fit (that is, its first parameter).
 .PP
 .I params
 may not be
@@ -26,7 +26,7 @@ may not be
 .PP
 The return value is
 .I params->hashlen
-if this number is 64 or less, otherwise the
+if this number is 64 or less, otherwise
 it will be larger than
 .I params->hashlen
 but no larger than
@@ -38,8 +38,8 @@ The
 function returns the number of bytes that the
 output buffer size for the
 .BR libar2_hash (3)
-function upon successful completion. On failure
-0 is returned and
+function must be upon successful completion.
+On failure 0 is returned and
 .I errno
 is set to describe the error.
 
diff --git a/libar2_init.3 b/libar2_init.3
index d14b31f..655d938 100644
--- a/libar2_init.3
+++ b/libar2_init.3
@@ -15,19 +15,20 @@ Link with
 .SH DESCRIPTION
 The
 .BR libar2_init ()
-function initialises the library, specifically
+function initialises the library. Specifically
 it selects which versions of different functions
 the library shall use, based on the capabilities
-of the machine that runs the function.
+of the machine that executes the function.
 .PP
 The
 .BR libar2_init ()
 function is called automatically by the
 .BR libar2_hash (3)
 function, but it is desirable, but not necessary,
-for multi-threaded applications to call it manually,
-also depending on the capabilities of the compiler
-and linker that was used to create the library, the
+for multi-threaded applications to call it manually.
+Additionally, depending on the capabilities of the
+compiler and linker that was used to create the
+library, the
 .BR libar2_init ()
 function may be called automatically at load-time.
 
diff --git a/libar2_string_to_type.3 b/libar2_string_to_type.3
index be199f9..cd99059 100644
--- a/libar2_string_to_type.3
+++ b/libar2_string_to_type.3
@@ -24,7 +24,7 @@ The
 .BR libar2_string_to_type ()
 function converts a string, provided via the
 .I str
-parameter, to a Argon2 primitive type and stores
+parameter, to an Argon2 primitive type and stores
 the constant that represents that type in
 .IR *typep .
 .PP
@@ -34,14 +34,14 @@ currently recognised strings, and are converted to
 .IR LIBAR2_ARGON2D ,
 .IR LIBAR2_ARGON2I ,
 .IR LIBAR2_ARGON2ID ,
-and.
+and
 .IR LIBAR2_ARGON2DS ,
 respectively.
 .PP
 The
 .BR libar2_string_to_type ()
-is case-insensitive and will recognise the
-dollar-sign
+function is case-insensitive and will
+recognise the dollar-sign
 .RB ( $ )
 character, or a NUL byte, as the end of the
 string.
diff --git a/libar2_string_to_version.3 b/libar2_string_to_version.3
index 40bdf00..80a34d6 100644
--- a/libar2_string_to_version.3
+++ b/libar2_string_to_version.3
@@ -26,7 +26,7 @@ parameter, to a version of the Argon2 family and
 stores the constant that represents that version in
 .IR *versionp .
 .PP
-The strings \(dq1.0\(dq and \(dq1.3\(dq, both either
+The strings \(dq1.0\(dq and \(dq1.3\(dq, both
 with or without the dot
 .RB ( . ),
 are the currently recognised strings, and are
diff --git a/libar2_type_to_string.3 b/libar2_type_to_string.3
index 74df041..08b52ec 100644
--- a/libar2_type_to_string.3
+++ b/libar2_type_to_string.3
@@ -47,8 +47,8 @@ If the
 .I casing
 parameter is
 .IR LIBAR2_TITLE_CASE ,
-the first character returned string will be in
-upper case, and the rest of the string will be
+the first character in the returned string will be
+in upper case, and the rest of the string will be
 in lower case, that is, for example \(dqArgon2d\(dq.
 If the
 .I casing
diff --git a/libar2_validate_params.3 b/libar2_validate_params.3
index 65e3d49..e8d3245 100644
--- a/libar2_validate_params.3
+++ b/libar2_validate_params.3
@@ -63,7 +63,7 @@ The
 function checks that the hashing parameters
 provided in the
 .I params
-parameters are valid and can be used for
+parameter are valid and can be used for
 hashing by the libar2 library. An error
 description will be stored in
 .I *errmsgp
@@ -95,8 +95,8 @@ is
 .IR NULL )
 if the input is valid. If the input is
 invalid, an error code (with a positive
-value) will returned and description of
-what is incorrect is stored in
+value) will be returned and a description
+of what is incorrect is stored in
 .I *errmsgp
 (unless
 .I errmsgp
@@ -104,7 +104,7 @@ is
 .IR NULL ).
 The return values that indicate invalid
 input, in the current version of the
-function are:
+function, are:
 .TP
 .B LIBAR2_T_COST_TOO_SMALL
 The time-cost parameter is too small.
@@ -122,7 +122,7 @@ The memory-cost parameter is too large.
 The lane-count parameter is too small.
 .TP
 .B LIBAR2_TOO_MANY_LANES
-The lane-count parameter is too large
+The lane-count parameter is too large.
 .TP
 .B LIBAR2_SALT_TOO_SMALL
 The salt parameter is too small.