Code doc progress

8 files changed, 312 insertions, 107 deletions

diff --git a/doc/fmts.md b/doc/fmts.md
index cfb875c..cac8061 100644
--- a/doc/fmts.md
+++ b/doc/fmts.md
@@ -36,11 +36,10 @@ Where
 | offset_n     | 16-bit unsigned integer offset to start of a data entry       |
 | data_entries | series of data entries                                        |
 
-**mask key** is 256-octet long mask key for masking *data* as a whole. It is
-randomly generated for each build(i.e. each time proone-mkdvault is invoked).
-**offset_***n* is an offset to the start of the *n*th data entry.
-**data_entries** is a series of data entries. The format of a data entry is
-described blow.
+**mask key** is 256-octet long mask key for masking. It is randomly generated
+for each build(i.e. each time proone-mkdvault is invoked). **offset_***n* is an
+offset to the start of the *n*th data entry. **data_entries** is a series of
+data entries. The format of a data entry is described blow.
 
 ```
     0                   1                   2                   3
@@ -67,8 +66,8 @@ the data type of the entry data. The definition of the values is described blow.
 | CSTR  | 0x00  | 8-bit narrow character string (UTF-8)                        |
 | BIN   | 0x02  | binary data in octet units                                   |
 
-Entry data is masked so that it can be accessed and unmasked randomly and
-possibly in parallel.
+All the fields excluding *salt* are kept masked. Entry data is masked so that it
+can be accessed and unmasked randomly and possibly in parallel.
 
 ```c
 for (size_t i = 0; i < size; i += 1) {
@@ -83,14 +82,14 @@ Where
 * mask: the mask key - the 256-elements-long array of 8-bit unsigned integers
 * salt: the 8-bit unsigned integer salt value
 
-As evident from the algorithm shown above, the salt value simply acts as a
-offset to the start of the mask key for the entry. In order to unmask an entry,
-the *data_size* field must be unmasked first to determine the length of the
-data. Once the length of the data is unmasked, the data part of the masked entry
-data can be unmasked using the same algorithm again. When the unmasked data
-entry is referenced and no longer needed, the entirety of the data must be
-masked back to the original form so that the data entries are kept obsecure in
-memory. This should be done immediately by calling `prne_dvault_reset()`.
+The salt value simply acts as a offset to the start of the mask key for the
+entry. In order to unmask an entry, the *data_size* field must be unmasked first
+to determine the length of the data. Once the length of the data is unmasked,
+the data part of the masked entry data can be unmasked using the same algorithm.
+When the unmasked data entry is referenced and no longer needed, the entirety of
+the data must be masked back to the original form so that the data entries are
+kept obsecure in memory. This should be done immediately by calling
+`prne_dvault_reset()`.
 
 Note that the total length of entries can be up to **around** 65,535 octets
 because offsets are represented in 16-bit unsigned integer values. Since DVault
diff --git a/src/bitfield.h b/src/bitfield.h
index d1c3dd7..71d0062 100644
--- a/src/bitfield.h
+++ b/src/bitfield.h
@@ -1,7 +1,8 @@
 /** \file The bit field implementation
  *
- * The bit field is a convenience set of functions for representing bits in
- * byte arrays. It is much like \c std::bitset but with \c data() equivalent.
+ * \note The bit field is a convenience set of functions for representing bits
+ * 	in byte arrays. It is much like \c std::bitset but with \c data()
+ * 	equivalent.
  */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
@@ -33,9 +34,9 @@
 
 /**
  * \brief Calculate the number of bytes required to store bits
- * \param nb_bits (integer value)the number of bits to store.
- * 	Must be zero or greater
- * \return the number of bytes required
+ * \param nb_bits The number of bits to store.
+ * 	Must be an integer zero or greater
+ * \return The number of bytes required
  */
 #define prne_bf_get_size(nb_bits)\
 	((nb_bits) % 8 == 0 ? (nb_bits) / 8 : (nb_bits) / 8 + 1)
@@ -43,9 +44,9 @@
 /**
  * \brief Function type, to be applied to each bit in the field. See
  *	\see prne_bf_foreach()
- * \param ctx the custom context object to be used in the function
- * \param bit the index of the bit
- * \param v the value of the bit. \c True if set. \c False if unset
+ * \param ctx The custom context object to be used in the function
+ * \param bit The index of the bit
+ * \param v The value of the bit. \c True if set. \c False if unset
  */
 typedef void(*prne_bf_foreach_ft)(
 	void *ctx,
@@ -54,19 +55,20 @@ typedef void(*prne_bf_foreach_ft)(
 
 /**
  * \brief Set the bit in the bit field.
- * \param bf the bit field to manipulate
- * \param bit the index of the bit to manipulate
- * \param v the new value of the bit. \c True to set, \c false to unset
+ * \param bf The bit field to manipulate
+ * \param bit The index of the bit to manipulate
+ * \param v The new value of the bit. \c True to set, \c false to unset
  */
 void prne_bf_set (uint8_t *bf, const unsigned int bit, const bool v);
 /**
  * \brief Extract the value of the bit in the bit field.
- * \param bf the bit field
- * \param size the size of the bit field in bytes
- * \param bit the index of the bit
+ * \param bf The bit field
+ * \param size The size of the bit field in bytes
+ * \param bit The index of the bit
  * \note \p size is used to determine if \p bit is out of bounds. The function
  * 	regards the bits outside the bounds of the bit field unset(false).
- * \return \c True if the bit is set.
+ * \retval True if the bit is set.
+ * \retval False if the bit is unset.
  */
 bool prne_bf_test (
 	const uint8_t *bf,
@@ -74,11 +76,11 @@ bool prne_bf_test (
 	const unsigned int bit);
 /**
  * \brief Iterate through the bit field, invoking \p f for each bit.
- * \param ctx the custom context to be passed to \p f
- * \param bf the bit field
- * \param size the size of the bit field in bytes
- * \param f the function to be invoked for each bit in the bit field
- * \note the number of times \p f is called is always a multiple of 8 regardless
+ * \param ctx The custom context to be passed to \p f
+ * \param bf The bit field
+ * \param size The size of the bit field in bytes
+ * \param f The function to be invoked for each bit in the bit field
+ * \note The number of times \p f is called is always a multiple of 8 regardless
  * 	of the actual number of bits in the field.
  */
 void prne_bf_foreach (
diff --git a/src/bne.h b/src/bne.h
index 397ae97..ef73bb1 100644
--- a/src/bne.h
+++ b/src/bne.h
@@ -113,7 +113,7 @@ struct prne_bne_param {
 		 * \brief The destination file name of the Proone executable (required)
 		 * \param ctx \c cb_ctx
 		 * \return A pointer to a null-terminated string.
-		 * \return Return null to indicate an unsuccessful operation. \c errno
+		 * \retval Null to indicate an unsuccessful operation. \c errno
 		 * 	should be set to an appropriate value.
 		 *
 		 * \note The returned memory must be writable and freeable with
@@ -129,10 +129,10 @@ struct prne_bne_param {
 		 * \brief The name of the upload lock file (optional)
 		 * \param ctx \c cb_ctx
 		 * \return A pointer to a null-terminated string.
-		 * \return Set \c errno to an appropriate value and return null to
-		 * 	indicate an unsuccessful operation.
-		 * \return Set \c errno to zero and return null to disable the use of
-		 * 	lock file.
+		 * \retval Null to indicate an unsuccessful operation with \c errno set
+		 * 	to an appropriate value.
+		 * \retval Null to disable the use of the lock file with \c errno set to
+		 * 	zero.
 		 *
 		 * \note The returned memory must be writable and freeable with
 		 * 	\c prne_free() The worker scrubs the string and frees it immediately
@@ -151,9 +151,9 @@ struct prne_bne_param {
 		/**
 		 * \brief Enter data dictionary callback (optional)
 		 * \param ctx \c cb_ctx
-		 * \return False if unable to enter the data dictionary. \c errno must
-		 * 	be set to an appropriate value.
-		 * \return True otherwise.
+		 * \retval False if unable to enter the data dictionary with \c errno
+		 * 	set to an appropriate value.
+		 * \retval True otherwise.
 		 *
 		 * \note \c exit_dd() is guaranteed to be invoked if returned true.
 		 * \note The function must always return true if \c cred_dict does not
@@ -182,7 +182,7 @@ struct prne_bne_param {
 		 * \brief Process uptime enquiry callback (optional)
 		 * \param ctx \c cb_ctx
 		 * \return The elapsed real time of the parent process in seconds.
-		 * \return \c UINT64_MAX to disable the uptime check for M2M binary
+		 * \retval \c UINT64_MAX to disable the uptime check for M2M binary
 		 * 	upgrade of the local instance or if process uptime information is
 		 * 	unavailable.
 		 * \see \c BNE_M2M_UPBIN_INT
@@ -197,10 +197,10 @@ struct prne_bne_param {
 		 * \brief Proone version comparator callback (optional)
 		 * \param ctx \c cb_ctx
 		 * \param uuid The version uuid of the remote instance.
-		 * \return A negative integer if \p uuid is newer than that of the local
+		 * \retval A negative integer if \p uuid is newer than that of the local
 		 * 	instance.
-		 * \return Zero if \p uuid is identical to that of the local instance.
-		 * \return A positive integer if \p uuid is older than that of the local
+		 * \retval Zero if \p uuid is identical to that of the local instance.
+		 * \retval A positive integer if \p uuid is older than that of the local
 		 * 	instance.
 		 *
 		 * \note Always returning zero effectively disables M2M binary upgrade.
@@ -224,8 +224,7 @@ struct prne_bne_param {
 		 * 	\c prne_free()
 		 * \return An open and valid file descriptor upon successful creation of
 		 * 	temporary file.
-		 * \return A negative integer otherwise. \c errno must be set to an
-		 * 	appropriate value.
+		 * \retval A negative integer with \c errno set to an appropriate value.
 		 *
 		 * \note
 		 * This is the callback function that the worker uses to create
@@ -249,9 +248,10 @@ struct prne_bne_param {
 		 * \param path The path to the new executable.
 		 * \param cmd The command line arguments without the first element,
 		 * 	which is the path to the executable.
-		 * \return True if the new executable is accepted and no error has
-		 * 	occurred during the process. False otherwise. \c errno may be set to
-		 * 	explain why the executable has not been accepted.
+		 * \retval True if the new executable is accepted and no error has
+		 * 	occurred during the process.
+		 * \retval False otherwise with \c errno set to explain why the
+		 * executable has not been accepted.
 		 *
 		 * \note
 		 * This function is called by the worker upon the successful download of
@@ -323,15 +323,17 @@ struct prne_bne_result {
  */
 void prne_init_bne_param (prne_bne_param_t *p);
 /**
- * \brief Free the resources allocated for the BNE worker parameter object.
+ * \brief Free the resources allocated for the BNE worker parameter object
  * \param p The pointer to the object that has been initialised using
  * 	\c prne_init_bne_param()
  */
 void prne_free_bne_param (prne_bne_param_t *p);
 
 /**
- * \brief Convert the enum value to a string describing the enum value
+ * \brief Convert the enum value to a descriptive string
  * \return A pointer to the string from the read-only static string pool.
+ * \retval Null if \p v is out of bounds of the valid range with \c errno set to
+ * 	\c EINVAL
  */
 const char *prne_bne_vector_tostr (const prne_bne_vector_t v);
 
diff --git a/src/build-utils.sh b/src/build-utils.sh
index 2ae926b..22b5208 100755
--- a/src/build-utils.sh
+++ b/src/build-utils.sh
@@ -1,4 +1,11 @@
 #!/bin/bash
+## \file
+# \brief Convenience shell functions for fabrication of Proone executables
+# \param 1 The subcommand. One of align-size, align-file, append-uint32 or
+# 	append-uint16
+# \param 2 or greator: arguments to the subcommand.
+# \note These shell functions are used in the Automake recipe to facilitate
+#	extra unconventional steps to build Proone executables.
 
 # Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 #
@@ -20,6 +27,11 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+##
+# \brief Align size x to y
+# \param 1 The alignment.
+# \param 2 The size to align.
+# \return The aligned size.
 cmd_align-size () {
 	local aligned
 
@@ -40,6 +52,10 @@ cmd_align-size () {
 	return 0
 }
 
+##
+# \brief Align the size of the file using truncate
+# \param 1 The alignment.
+# \param 2 The path to the file to align.
 cmd_align-file () {
 	if [ $# -lt 2 ]; then
 		echo "Usage: $0 <alignment> <file>" >&2
@@ -49,6 +65,10 @@ cmd_align-file () {
 	truncate -s $("$SELF" align-size "$1" $(stat -c "%s" $2)) "$2"
 }
 
+##
+# \brief Append a 32-bit unsigned integer to the file, MSB first
+# \param 1 The integer value to append
+# \param 2 The file to append the integer to
 cmd_append-uint32 () {
 	local a b c d
 
@@ -68,6 +88,10 @@ cmd_append-uint32 () {
 	printf "\\x$a\\x$b\\x$c\\x$d" >> "$2"
 }
 
+##
+# \brief Append a 16-bit unsigned integer to the file, MSB first
+# \param 1 The integer value to append
+# \param 2 The file to append the integer to
 cmd_append-uint16 () {
 	local a b
 
diff --git a/src/config.h b/src/config.h
index 92932de..1b2a746 100644
--- a/src/config.h
+++ b/src/config.h
@@ -1,3 +1,10 @@
+/** \file
+ * \brief The general project configuration
+ * \note This header defines "static" macros, which include system config
+ * 	detection mechanism, option values for external libraries used across the
+ * 	project and project meta data such as version info.
+ *
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -32,6 +39,10 @@
 
 #include <zlib.h>
 
+/** \def PRNE_HOST_WORDSIZE
+ * \brief Th system "word size". 32 if the system is a 32-bit machine. 64 if the
+ * 	system is a 64-bit machine.
+ */
 #if INTPTR_MAX == INT32_MAX
 	#define PRNE_HOST_WORDSIZE 32
 #elif INTPTR_MAX == INT64_MAX
@@ -40,29 +51,51 @@
 	#error "FIXME!"
 #endif
 
+// The program version
 #define PRNE_PROG_VER {\
 	0x11, 0xf7, 0x6b, 0x87, 0x62, 0x1a, 0x47, 0x9c,\
 	0xa2, 0x18, 0x5c, 0x55, 0x40, 0x33, 0x7c, 0x9f\
 }
+/**
+ * \brief The shared global file name salt value
+ * \note This is the protocol uuid used as the salt value for calculating the
+ * 	hashed name of the shm file.
+ * \see prne_shared_global
+ */
 #define PRNE_SHG_SALT {\
 	0x31, 0xe4, 0xf1, 0x7c, 0xdb, 0x76, 0x43, 0x32,\
 	0xaf, 0x48, 0xfd, 0x9f, 0xb8, 0x45, 0x3f, 0x8f\
 }
 
+/**
+ * \brief The version matrix
+ * \note The version matrix is a array of previous known version uuids of
+ * 	Proone. The byte size of the array must be a multiple of 16.
+ * \note If there's no previous version, the array must contain one or more
+ * 	placeholder versions because the ISO-C does not allow empty initialiser
+ * 	lists. The placeholder versions may be used to reserve uuids for future
+ * 	versions.
+ */
 #define PRNE_VER_MAT {\
 	/* 76f2f748-3b6f-420c-abd7-e9929a0b67d6: placeholder version 1 */\
-	/* Remove it when you add the first old version */\
+	/* Remove/replace it when you add the first old version */\
 	0x76, 0xf2, 0xf7, 0x48, 0x3b, 0x6f, 0x42, 0x0c,\
 	0xab, 0xd7, 0xe9, 0x92, 0x9a, 0x0b, 0x67, 0xd6,\
 	/* ce6fe199-5595-49a1-96c6-261d1cce9e32: placeholder version 2 */\
-	/* Remove it when you add the first old version */\
+	/* Remove/replace it when you add the first old version */\
 	0xce, 0x6f, 0xe1, 0x99, 0x55, 0x95, 0x49, 0xa1,\
 	0x96, 0xc6, 0x26, 0x1d, 0x1c, 0xce, 0x9e, 0x32\
 }
 
+// The common zlib compression level
 #define PRNE_PACK_Z_LEVEL Z_DEFAULT_COMPRESSION
 
-// PRNE_HOST_ARCH
+/** \def PRNE_HOST_ARCH
+ * \brief The system CPU architecture
+ * \note Compiler-specific macros are used. Expand this macro to support other
+ * 	compilers.
+ * \see prne_arch_t
+ */
 #ifdef __GNUC__
 	#if defined(__i386__)
 		#define PRNE_HOST_ARCH PRNE_ARCH_I686
@@ -103,7 +136,12 @@
 	#error "FIXME!"
 #endif
 
-// PRNE_HOST_OS
+/** \def PRNE_HOST_OS
+ * \brief The system operating system
+ * \note Compiler-specific macros are used. Expand this macro to support other
+ * 	compilers.
+ * \see prne_os_t
+ */
 #ifdef __GNUC__
 	#if defined(__linux__)
 		#define PRNE_HOST_OS PRNE_OS_LINUX
diff --git a/src/cred_dict.h b/src/cred_dict.h
index b07bb4a..2528a5d 100644
--- a/src/cred_dict.h
+++ b/src/cred_dict.h
@@ -1,3 +1,6 @@
+/** \file
+ * \brief The credential dictionary implementation
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -24,37 +27,73 @@
 #include <stddef.h>
 #include <stdbool.h>
 
-
+/* Alias declaration */
 typedef struct prne_cred_dict_entry prne_cred_dict_entry_t;
 typedef struct prne_cred_dict_raw_entry prne_cred_dict_raw_entry_t;
 typedef struct prne_cred_dict prne_cred_dict_t;
 
+// The index entry object
 struct prne_cred_dict_entry {
-	uint16_t id;
-	uint16_t pw;
-	uint8_t weight;
+	uint16_t id; // Index of start of the user name
+	uint16_t pw; // Index of start of the password
+	uint8_t weight; // The weight value
 };
 
+// The raw entry entry object used to build the dictionary
 struct prne_cred_dict_raw_entry {
-	char *id;
-	char *pw;
-	uint8_t weight;
+	char *id; // Pointer to the user name string
+	char *pw; // Pointer to the password string
+	uint8_t weight; // Weight value
 };
 
+// The dictionary object
 struct prne_cred_dict {
-	const char *m;
+	const char *m; // Pointer to the string pool
 	prne_cred_dict_entry_t *arr;
 	size_t cnt;
 };
 
+/**
+ * \brief Initialise the credential dictionary object
+ * \note Initialises the members of \p p to initial values. Prepares \p p so
+ * 	that it can be freed using \c prne_free_cred_dict()
+ */
 void prne_init_cred_dict (prne_cred_dict_t *p);
+/**
+ * \brief Free the resources allocated for the credential dictionary object.
+ * \param p The pointer to the object that has been initialised using
+ * 	\c prne_init_cred_dict()
+ */
 void prne_free_cred_dict (prne_cred_dict_t *p);
 
+/**
+ * \brief Build a credential dictionary
+ * \param arr The raw entries.
+ * \param cnt The number of entries in \p arr
+ * \param[out] out_m The serialised credential dictionary deserialisable with
+ * 	\c prne_dser_cred_dict(). The returned memory is freeable with
+ * 	\c prne_free().
+ * \param[out] out_l The length of \p out_m in bytes.
+ * \retval True if successful.
+ * \retval False on error with \c errno set to an appropriate value.
+ * \note The size of the binary credential dictionary is limited to 2^16 bytes
+ * 	as indices are 16-bit integers. \c E2BIG is used to indicate this error.
+ */
 bool prne_build_cred_dict (
 	const prne_cred_dict_raw_entry_t *arr,
 	const size_t cnt,
 	uint8_t **out_m,
 	size_t *out_l);
+/**
+ * \brief Deserialise the credential dictionary
+ * \param[out] dict The output object. Must be initiaised with
+ * 	\c prne_init_cred_dict() beforehand.
+ * \param buf The pointer to the memory containing the serialised credential
+ * 	dictionary.
+ * \param len The readable length of \p buf in bytes.
+ * \retval True on successful parsing and allocation of \p dict members.
+ * \retval False otherwise with \c errno set to an appropriate value.
+ */
 bool prne_dser_cred_dict (
 	prne_cred_dict_t *dict,
 	const uint8_t *buf,
diff --git a/src/data.h b/src/data.h
index 984d6bc..9343c10 100644
--- a/src/data.h
+++ b/src/data.h
@@ -1,3 +1,8 @@
+/** \file
+ * \brief The data vault entry key definitions
+ * \note This header defines \c prne_data_key_t. The enum is defined in the
+ * 	separate header for ease of use with VCS.
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -23,29 +28,35 @@
 #include "util_ct.h"
 
 
+/**
+ * \brief The data vault entry key enum
+ * \note Suitable storage type: int8_t
+ */
 typedef enum {
-	PRNE_DATA_KEY_NONE = -1,
+	PRNE_DATA_KEY_NONE = -1, // Null value
 
-	PRNE_DATA_KEY_PROG_VER,
-	PRNE_DATA_KEY_SHG_SALT,
-	PRNE_DATA_KEY_X509_CA_CRT,
-	PRNE_DATA_KEY_X509_DH,
-	PRNE_DATA_KEY_X509_S_CRT,
-	PRNE_DATA_KEY_X509_S_KEY,
-	PRNE_DATA_KEY_X509_C_CRT,
-	PRNE_DATA_KEY_X509_C_KEY,
-	PRNE_DATA_KEY_RESOLV_NS_IPV4,
-	PRNE_DATA_KEY_RESOLV_NS_IPV6,
-	PRNE_DATA_KEY_CNC_TXT_REC,
+	PRNE_DATA_KEY_PROG_VER, // The 16-byte program version uuid
+	PRNE_DATA_KEY_SHG_SALT, // The 16-byte shared global salt value
+	PRNE_DATA_KEY_X509_CA_CRT, // The heartbeat PKI CA certificate chain
+	PRNE_DATA_KEY_X509_DH, // The heartbeat PKI DH param
+	PRNE_DATA_KEY_X509_S_CRT, // The heartbeat PKI server certificate
+	PRNE_DATA_KEY_X509_S_KEY, // The heartbeat PKI server private key
+	PRNE_DATA_KEY_X509_C_CRT, // The heartbeat PKI client certificate
+	PRNE_DATA_KEY_X509_C_KEY, // The heartbeat PKI client private key
+	PRNE_DATA_KEY_RESOLV_NS_IPV4, // The resolv IPv4 DNS name server pool
+	PRNE_DATA_KEY_RESOLV_NS_IPV6, // The resolv IPv6 DNS name server pool
+	PRNE_DATA_KEY_CNC_TXT_REC, // The name of the heartbeat CNC TXT record
+	// The destination ports of the SYN packets crafted by the recon worker
 	PRNE_DATA_KEY_RCN_PORTS,
-	PRNE_DATA_KEY_RCN_T_IPV4,
-	PRNE_DATA_KEY_RCN_BL_IPV4,
-	PRNE_DATA_KEY_RCN_T_IPV6,
-	PRNE_DATA_KEY_RCN_BL_IPV6,
-	PRNE_DATA_KEY_CRED_DICT,
+	PRNE_DATA_KEY_RCN_T_IPV4, // The target recon IPv4 networks
+	PRNE_DATA_KEY_RCN_BL_IPV4, // The blacklist recon IPv4 networks
+	PRNE_DATA_KEY_RCN_T_IPV6,  // The target recon IPv6 networks
+	PRNE_DATA_KEY_RCN_BL_IPV6, // The blacklist recon IPv6 networks
+	PRNE_DATA_KEY_CRED_DICT, // The serialised credential dictionary
+	// The name of the Proone executable. Used by the BNE worker.
 	PRNE_DATA_KEY_EXEC_NAME,
-	PRNE_DATA_KEY_VER_MAT,
-	PRNE_DATA_KEY_BNE_LOCK_NAME,
+	PRNE_DATA_KEY_VER_MAT, // The version matrix
+	PRNE_DATA_KEY_BNE_LOCK_NAME, // The name of the BNE lock file
 
-	NB_PRNE_DATA_KEY
+	NB_PRNE_DATA_KEY // Meta value: the number of enums excluding the null value
 } prne_data_key_t;
diff --git a/src/dvault.h b/src/dvault.h
index 3c1872e..0f52518 100644
--- a/src/dvault.h
+++ b/src/dvault.h
@@ -1,3 +1,6 @@
+/** \file
+ *  \brief The data vault implementation
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -27,36 +30,69 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-
+/* Alias declarations */
 typedef struct prne_dvault_mask_result prne_dvault_mask_result_t;
 typedef struct prne_dvault prne_dvault_t;
 
+/**
+ * \brief The data type for the entry
+ * \note Suitable storage type: int8_t
+ */
 typedef enum {
-	PRNE_DATA_TYPE_NONE = -1,
+	PRNE_DATA_TYPE_NONE = -1, // Null value
 
+	// Null-terminated narrow character string, usually in UTF-8 encoding
 	PRNE_DATA_TYPE_CSTR,
-	PRNE_DATA_TYPE_BIN,
+	PRNE_DATA_TYPE_BIN, // Binary data
 
-	NB_PRNE_DATA_TYPE
+	NB_PRNE_DATA_TYPE // Meta value: the number of enums
 } prne_data_type_t;
 PRNE_LIMIT_ENUM(prne_data_type_t, NB_PRNE_DATA_TYPE, 0xFF);
 
+// The masking operation result code
 typedef enum {
-	PRNE_DVAULT_MASK_OK,
-	PRNE_DVAULT_MASK_MEM_ERR,
-	PRNE_DVAULT_MASK_TOO_LARGE,
-	PRNE_DVAULT_MASK_INVALID_TYPE
+	PRNE_DVAULT_MASK_OK, // Success
+	PRNE_DVAULT_MASK_MEM_ERR, // Memory allocation error
+	PRNE_DVAULT_MASK_TOO_LARGE, // Entry data too large
+	PRNE_DVAULT_MASK_INVALID_TYPE // Invalid prne_data_type_t
 } prne_dvault_mask_result_code_t;
 
+// The masking operation result object
 struct prne_dvault_mask_result {
-	size_t size;
-	uint8_t *data;
+	size_t size; // The length of data in bytes
+	uint8_t *data; // The masked data
+	/* The result code.
+	 * size and data are valid only if the result code is PRNE_DVAULT_MASK_OK.
+	 */
 	prne_dvault_mask_result_code_t result;
 };
 
 
+/**
+ * \brief Convert the enum value to a descriptive string
+ * \return A pointer to the string from the read-only static string pool.
+ * \retval Null if \p t is out of bounds of the valid range with \c errno set to
+ * 	\c EINVAL
+ */
 const char *prne_data_type_tostr (const prne_data_type_t t);
+/**
+ * \brief The inverse function of \c prne_data_type_tostr()
+ * \retval PRNE_DATA_TYPE_NONE if \p str does not match any enum. \c errno set
+ * 	to \c EINVAL
+ * \return The parsed enum
+ */
 prne_data_type_t prne_data_type_fstr (const char *str);
+/**
+ * \brief Mask or unmask memory using parameters
+ * \param size The length of \p m, in bytes, to invert.
+ * \param m The memory to invert
+ * \param salt The salt offset
+ * \param salt_ofs The offset in addition to \p salt
+ * \param mask The pointer to the 256-byte mask key
+ * \note This is a primitve function that "inverts" a portion of memory to mask
+ * 	the original data or to unmask the masked data.
+ * \note The final offset is \p salt plus \p salt_ofs.
+ */
 void prne_dvault_invert_mem (
 	const size_t size,
 	void *m,
@@ -64,30 +100,84 @@ void prne_dvault_invert_mem (
 	const size_t salt_ofs,
 	const uint8_t *mask);
 
+/**
+ * \brief Initialise the data vault masking operation result object
+ * \note Initialises the members of \p r to initial values. Prepares \p r so
+ * 	that it can be freed using \c prne_free_dvault_mask_result()
+ */
 void prne_init_dvault_mask_result (prne_dvault_mask_result_t *r);
+/**
+ * \brief Free the resources allocated for the the data vault masking operation
+ * 	result object
+ * \param p The pointer to the object that has been initialised using
+ * 	\c prne_init_dvault_mask_result()
+ */
 void prne_free_dvault_mask_result (prne_dvault_mask_result_t *r);
+/**
+ * \brief Mask the source data
+ * \param type The data type of the source data.
+ * \param salt The randomly generated salt value.
+ * \param mask The 256-byte mask key.
+ * \param data_size The length of \p data in bytes.
+ * \param data The source data.
+ * \return An instance of the data vault masking operation object, with memory
+ * 	allocated to return the masked data. The instance must always be freed using
+ * 	\c prne_free_dvault_mask_result() regardless of the result code.
+ */
 prne_dvault_mask_result_t prne_dvault_mask (
 	const prne_data_type_t type,
 	const uint8_t salt,
 	const uint8_t *mask,
 	const size_t data_size,
 	const uint8_t *data);
+/**
+ * \brief Convert the enum value to a descriptive string
+ * \return A pointer to the string from the read-only static string pool.
+ * \retval Null if \p code is out of bounds of the valid range with \c errno set
+ * 	to \c EINVAL
+ */
 const char *prne_dvault_mask_result_tostr (
 	const prne_dvault_mask_result_code_t code);
 
-/* prne_init_dvault(const void *m)
-*
-* ARGS:
-*	m: pointer to start of readable and writable a dvault made by
-*		proone-mkdvault. This region of memory must be writable.
-*/
+/**
+ * \brief Initialise the internal global variables with the data vault binary
+ * \param m The pointer to the binary data dump. The memory must be readable and
+ * 	writeable. The data dump is produced by proone-mkdvault
+ * \note The function cannot be called again without calling
+ * 	\c prne_deinit_dvault() beforehand.
+ * \warning The behaviour is undefined if the data at \p m is not valid.
+ */
 void prne_init_dvault (const void *m);
-/* prne_deinit_dvault (const void *m)
-*
-* Calls prne_dvault_reset(). Revert changes to the data vault memory.
-*/
+/**
+ * \brief Deinitialise the internal global variables and resources allocated for
+ * 	the data vault
+ * \note \c prne_init_dvault() can be called when the function returns.
+ */
 void prne_deinit_dvault (void);
-// len: strlen()
+/**
+ * \brief Unmask and get the pointer to the string from the entry
+ * \param key The key to the entry.
+ * \param[out] len (optional)The length of the string, excluding the null
+ * 	terminator.
+ * \return The pointer to the unmasked string from the entry.
+ * \warning The behaviour is undefined if the data entry at \p key is not of
+ * 	string or \p key is out of bounds.
+ */
 const char *prne_dvault_get_cstr (const prne_data_key_t key, size_t *len);
+/**
+ * \brief Unmask and get the pointer to the binary data from the entry
+ * \param key The key to the entry.
+ * \param[out] len (optional)The length of the data in bytes.
+ * \return The pointer to the unmasked binary data from the entry.
+ * \warning The behaviour is undefined if the data entry at \p key is not of
+ * 	binary data or \p key is out of bounds.
+ */
 const uint8_t *prne_dvault_get_bin (const prne_data_key_t key, size_t *len);
+/**
+ * \brief Mask all the data currently unmmasked
+ * \note This function has to be called soon after the unmasked data entry is
+ * 	no longer required.
+ * \warning The behaviour is undefined if the data vault is not initialised with
+ * 	\c prne_init_dvault()
+ */
 void prne_dvault_reset (void);