Documentation progress, bug fix, interface change

* Update vscode settings for Doxygen
* Fix mem leak in prne_index_bin_archive()
* Fix bug where errno is not set in prne_htbt_parse_args()
* Change names of parameter to prne_htbt_cp_hover()
* Add template for Doxygen comment blocks

9 files changed, 1081 insertions, 263 deletions

diff --git a/doc/htbt.md b/doc/htbt.md
index 7bf5f64..4fc9fb5 100644
--- a/doc/htbt.md
+++ b/doc/htbt.md
@@ -302,7 +302,7 @@ representation from/to two's complement representation.
 |           |       | required is not implemented                              |
 | PROTO_ERR | 0x02  | Protocol error was detected while processing frames      |
 | ERRNO     | 0x03  | Operation was not successful and *err* is set to errno   |
-| SUB       | 0x04  | *err* is set to the error code returned from the  module |
+| SUB       | 0x04  | *err* is set to the error code returned from the module  |
 | LIMIT     | 0x05  | Request could not be served because a limit was reached  |
 
 ### Hostinfo Frame
@@ -747,7 +747,7 @@ The submissive host is allowed to choose an alternative architecture if the one
 requested is unavailable when the **C**("compat") flag is set. The submissive
 host is required to transmit the copy of its executable if **S**("self") is set.
 The binary recombination target is specified in **os** and **arch** fields.
-These fields are ignored if *S* is set.
+These fields are ignored if **S** is set.
 
 ## Enum Codes
 ### CPU Architecture Codes
@@ -781,7 +781,7 @@ More on arch codes in [dev_notes](dev_notes.md).
 | Enum    | Value | Description                                                |
 | ------- | ----- | ---------------------------------------------------------- |
 | NONE    | 0x00  | Special value used to indicate that the code is not used   |
-| LINUX   | 0x01  | Linux ABI                                                  |
+| LINUX   | 0x01  | Linux ABI (Linux Standard Base)                            |
 
 The OS codes are used to represent the ABI the executable is compiled against.
 Proone is designed with portability in mind and OS codes will be used to
diff --git a/proone.code-workspace b/proone.code-workspace
index 392cc94..a2fe85e 100644
--- a/proone.code-workspace
+++ b/proone.code-workspace
@@ -20,6 +20,16 @@
 			"-Wall",
 			"-Wextra",
 			"-Wno-switch",
-			"-Wno-unused-parameter"]
+			"-Wno-unused-parameter"
+		],
+		"doxdocgen.cpp.tparamTemplate": "\\tparam {param} ",
+		"doxdocgen.file.versionTag": "\\version 0.1",
+		"doxdocgen.file.fileTemplate": "\\file {name}",
+		"doxdocgen.generic.authorTag": "\\author {author} ({email})",
+		"doxdocgen.generic.briefTemplate": "\\brief {text}",
+		"doxdocgen.generic.commandSuggestionAddPrefix": true,
+		"doxdocgen.generic.dateTemplate": "\\date {date}",
+		"doxdocgen.generic.paramTemplate": "\\param {param} ",
+		"doxdocgen.generic.returnTemplate": "\\return {type} "
 	}
 }
diff --git a/src/pack.c b/src/pack.c
index 8042526..774c21e 100644
--- a/src/pack.c
+++ b/src/pack.c
@@ -115,6 +115,7 @@ prne_pack_rc_t prne_index_bin_archive (
 		len -= 8;
 	}
 
+	prne_free_bin_archive(out);
 	out->data = data;
 	out->data_size = len;
 	out->nb_bin = nb_bin;
diff --git a/src/pack.h b/src/pack.h
index c487b00..aa7f64c 100644
--- a/src/pack.h
+++ b/src/pack.h
@@ -1,3 +1,6 @@
+/** \file
+ * \brief Executable packing facility.
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -28,46 +31,62 @@
 #include <zlib.h>
 
 
+/* Alias declarations */
 typedef struct prne_bin_host prne_bin_host_t;
 typedef struct prne_bin_tuple prne_bin_tuple_t;
 typedef struct prne_bin_archive prne_bin_archive_t;
 typedef struct prne_bin_rcb_ctx prne_bin_rcb_ctx_t;
 typedef struct prne_rcb_param prne_rcb_param_t;
 
+// The pack function result codes
 typedef enum {
-	PRNE_PACK_RC_OK,
-	PRNE_PACK_RC_EOF,
-	PRNE_PACK_RC_INVAL,
-	PRNE_PACK_RC_FMT_ERR,
-	PRNE_PACK_RC_ERRNO,
-	PRNE_PACK_RC_Z_ERR,
-	PRNE_PACK_RC_NO_ARCH,
-	PRNE_PACK_RC_UNIMPL_REV,
-
-	NB_PRNE_PACK_RC
+	PRNE_PACK_RC_OK, // Successful
+	PRNE_PACK_RC_EOF, // End of file reached
+	PRNE_PACK_RC_INVAL, // Invalid data
+	PRNE_PACK_RC_FMT_ERR, // Format error
+	PRNE_PACK_RC_ERRNO, // Syscall error, errno set
+	PRNE_PACK_RC_Z_ERR, // zlib function error
+	PRNE_PACK_RC_NO_ARCH, // Arch not found
+	PRNE_PACK_RC_UNIMPL_REV, // Unimplemented revision number
+
+	NB_PRNE_PACK_RC // Meta: the number of result codes
 } prne_pack_rc_t;
 
+// The executable host info record
 struct prne_bin_host {
 	prne_os_t os;
 	prne_arch_t arch;
 };
 
+// The executable host info record - executable size pair
 struct prne_bin_tuple {
 	size_t size;
 	prne_bin_host_t host;
 };
 
+// The indexed binary archive object
 struct prne_bin_archive {
-	const uint8_t *data;
-	size_t data_size;
-	size_t nb_bin;
-	prne_bin_tuple_t *bin;
+	const uint8_t *data; // The pointer to the start of the binary archive
+	size_t data_size; // The byte length of the binary archive
+	size_t nb_bin; // The number of the tuples
+	prne_bin_tuple_t *bin; // The array of the tuples
 };
 
-// Recombination Context
+// The recombination context object
 struct prne_bin_rcb_ctx {
-	void *o_ctx;
+	void *o_ctx; // The opaque context
+	/**
+	 * \brief The function used to free the opaque context. Not to be used
+	 *	directly.
+	 * \note Use \c prne_free_bin_rcb_ctx() to free the object!
+	 * \see \c prne_free_bin_rcb_ctx()
+	 */
 	void (*ctx_free_f)(void*);
+	/**
+	 * \brief The adaptive read callback function. Not to be used directly.
+	 * \note Use \c prne_bin_rcb_read()
+	 * \see \c prne_bin_rcb_read()
+	 */
 	ssize_t(*read_f)(
 		prne_bin_rcb_ctx_t *ctx,
 		uint8_t *buf,
@@ -76,6 +95,13 @@ struct prne_bin_rcb_ctx {
 		int *err);
 };
 
+/**
+ * \brief The recombination parameter object for initiating binary
+ *	recombination. The members are the parameters to \c prne_start_bin_rcb()
+ *	call excluding the target info. An instance of this object is set up on
+ *	program initialisation and shared globally.
+ * \see \c prne_start_bin_rcb()
+ */
 struct prne_rcb_param {
 	const uint8_t *m_self;
 	size_t self_len;
@@ -86,20 +112,96 @@ struct prne_rcb_param {
 	const prne_bin_host_t *self;
 };
 
+/**
+ * \brief The binary archive identity magic "pr-ba"
+ * \see /doc/fmts.md
+ */
 static const char PRNE_PACK_BA_IDEN_DATA[] = { 'p', 'r', '-', 'b', 'a' };
+/**
+ * \brief The nybin file format identity magic "nybin"
+ * \see /doc/fmts.md
+ */
 static const char PRNE_PACK_NYBIN_IDEN_DATA[] = { 'n', 'y', 'b', 'i', 'n' };
 
+/**
+ * \brief The equality operator of the executable host info record
+ * \retval true if the contents of the records are equal.
+ * \retval false otherwise.
+ */
 bool prne_eq_bin_host (const prne_bin_host_t *a, const prne_bin_host_t *b);
+/**
+ * \brief The in-range operator of the executable host info record. Check both
+ *	enums are in range(ie, recognised by the current implementation).
+ * \retval true if the enums are in range.
+ * \retval false otherwise.
+ */
 bool prne_bin_host_inrange (const prne_bin_host_t *x);
+/**
+ * \brief Initialise the indexed binary archive object.
+ * \note \p a can be freed using \c prne_free_bin_archive() once initialised.
+ * \see \c prne_free_bin_archive()
+ */
 void prne_init_bin_archive (prne_bin_archive_t *a);
+/**
+ * \brief Free resources allocated for the indexed binary archive object.
+ * \see \c prne_init_bin_archive()
+ */
 void prne_free_bin_archive (prne_bin_archive_t *a);
+/**
+ * \brief Index the binary archive from the binary.
+ * \param data The binary data, usually the address obtained using \c mmap() on
+ *	the executable.
+ * \param len The byte length of the binary data.
+ * \param[out] out The pointer to the binary archive object for index info.
+ * \retval PRNE_PACK_RC_OK The binary archive has been successfully index and
+ *	\p out is ready to use.
+ * \retval PRNE_PACK_RC_FMT_ERR The binary could not be parsed due to a format
+ *	error.
+ * \retval PRNE_PACK_RC_UNIMPL_REV An unimplemented revision number encountered.
+ * \retval PRNE_PACK_RC_ERRNO A memory allocation error has occurred. \c errno
+ *	is set to \c ENOMEM
+ * \note Any resource allocated previously for \p out is freed using
+ *	\c prne_free_bin_archive() if the operation is successful.
+ */
 prne_pack_rc_t prne_index_bin_archive (
 	const uint8_t *data,
 	size_t len,
 	prne_bin_archive_t *out);
 
+/**
+ * \brief Initialise the recombination context object.
+ * \see \c prne_free_bin_rcb_ctx()
+ */
 void prne_init_bin_rcb_ctx (prne_bin_rcb_ctx_t *ctx);
+/**
+ * \brief Free resources allocated for the recombination context object.
+ * \see \c prne_init_bin_rcb_ctx()
+ */
 void prne_free_bin_rcb_ctx (prne_bin_rcb_ctx_t *ctx);
+/**
+ * \brief Initiate binary recombination. Get the recombination context object
+ *	ready for \c prne_bin_rcb_read()
+ * \param ctx The recombination context object.
+ * \param target The recombination target host info.
+ * \param self The executable host info record of the running executable.
+ * \param m_self The pointer to the start of the running executable (the image
+ *	of the current process). Usually the address obtained using \c mmap()
+ * \param self_len The total byte length of the running executable(the size of
+ *	the file).
+ * \param exec_len The byte length of the ELF part of the running executable.
+ * \param m_dvault The pointer to the start of the data vault binary.
+ * \param dvault_len The byte length of the data vault binary.
+ * \param ba The indexed binary archive object.
+ * \retval PRNE_PACK_RC_OK if the initiation was successful.
+ * \retval PRNE_PACK_RC_INVAL if \p ba is NULL, or \p target or \p self is not
+ *	in range.
+ * \retval PRNE_PACK_RC_ERRNO if a memory allocation error has occurred and
+ *	\c errno is set to \c ENOMEM
+ * \retval PRNE_PACK_RC_NO_ARCH if \p ba does not contain the executable for
+ *	\p target
+ * \retval PRNE_PACK_RC_Z_ERR if a zlib function returned an error. Probably
+ *	allocation error or an incompatible zlib variant.
+ */
 prne_pack_rc_t prne_start_bin_rcb (
 	prne_bin_rcb_ctx_t *ctx,
 	const prne_bin_host_t target,
@@ -110,6 +212,14 @@ prne_pack_rc_t prne_start_bin_rcb (
 	const uint8_t *m_dvault,
 	const size_t dvault_len,
 	const prne_bin_archive_t *ba);
+/**
+ * \brief A variant of \c prne_start_bin_rcb() that try to initiate for a
+ *	compatible arch target on \c PRNE_PACK_RC_NO_ARCH
+ * \param[out] actual The pointer to the executable host info record for
+ *	returning the actual target initiated (optional)
+ * \see \c prne_start_bin_rcb()
+ * \see \c prne_compat_arch()
+ */
 prne_pack_rc_t prne_start_bin_rcb_compat (
 	prne_bin_rcb_ctx_t *ctx,
 	const prne_bin_host_t target,
@@ -121,6 +231,26 @@ prne_pack_rc_t prne_start_bin_rcb_compat (
 	const size_t dvault_len,
 	const prne_bin_archive_t *ba,
 	prne_bin_host_t *actual);
+/**
+ * \brief Read the recombined binary.
+ * \param ctx The initiated recombination context object.
+ * \param buf The output buffer.
+ * \param len The number of bytes available in \p buf
+ * \param[out] prc The pointer to a pack function result code variable(optional)
+ * \param[out] err The pointer to an int for library function return values
+ *	(optional)
+ * \return The number of bytes written to \p buf
+ * \retval 0 with \p prc PRNE_PACK_RC_OK means no data could be produced in a
+ *	reasonable amount of CPU time and the function had to return for other
+ *	threads. This is not an error and the function may be called again with the
+ *	same arguments after yielding to other threads.
+ * \retval 0 with \p prc PRNE_PACK_RC_EOF means all the data for the target
+ *	has been produced and the output file can be closed. The subsequent calls
+ *	will result in the same return values.
+ * \retval -1 on error. \p ctx cannot be used for read and must be freed or
+ *	reinitialised. \p prc is set to either \c PRNE_PACK_RC_ERRNO or
+ *	\c PRNE_PACK_RC_Z_ERR
+ */
 ssize_t prne_bin_rcb_read (
 	prne_bin_rcb_ctx_t *ctx,
 	uint8_t *buf,
@@ -128,6 +258,20 @@ ssize_t prne_bin_rcb_read (
 	prne_pack_rc_t *prc,
 	int *err);
 
+/**
+ * \brief Index the NYBIN file. The file must be mmaped first.
+ * \param[in] m_nybin The pointer to the start of the contents of the NYBIN file.
+ * \param[in] nybin_len The byte length of the contents of the NYBIN file.
+ * \param[out] m_dv The start of the data vault.
+ * \param[out] dv_len The byte length of the data vault.
+ * \param[out] m_ba The start of the binary archive.
+ * \param[out] ba_len The byte length of the binary archive.
+ * \retval true if the parsing was successful and the output parameters are all
+ *	set.
+ * \retval false with \c errno set to \c EPROTO on invalid format.
+ * \retval false with \c errno set to \c ENOSYS if the revision of the file is
+ *	unrecognised.
+ */
 bool prne_index_nybin (
 	const uint8_t *m_nybin,
 	const size_t nybin_len,
@@ -136,9 +280,29 @@ bool prne_index_nybin (
 	const uint8_t **m_ba,
 	size_t *ba_len);
 
+/**
+ * \brief Initialise the recombination parameter object. Reserved for any
+ *	dynamically allocated members in the future.
+ */
 void prne_init_rcb_param (prne_rcb_param_t *rp);
+/**
+ * \brief Free resources allocated for the recombination parameter object.
+ *	Reserved for any dynamically allocated members in the future.
+ */
 void prne_free_rcb_param (prne_rcb_param_t *rp);
 
+/**
+ * \brief Get the array of the compatible arches for \p arch
+ * \retval NULL if there's no known compatible arch for \p arch
+ * \return The pointer to an internal array, terminated by \c PRNE_ARCH_NONE
+ * \see \c prne_start_bin_rcb_compat()
+ * \note This function can be used to examine the "compat tree" of the arches.
+ */
 const prne_arch_t *prne_compat_arch (const prne_arch_t arch);
 
+/**
+ * \brief Get the descriptive string for the enum value.
+ * \retval NULL if \p prc is not in range.
+ * \return The pointer to the internal string describing the enum value.
+ */
 const char *prne_pack_rc_tostr (const prne_pack_rc_t prc);
diff --git a/src/proone.c b/src/proone.c
index dae5fad..3f44b33 100644
--- a/src/proone.c
+++ b/src/proone.c
@@ -1162,6 +1162,8 @@ static bool init_shared_global (void) {
 		// Session init code goes here
 		prne_memzero(prne_s_g->upbin_path, sizeof(prne_s_g->upbin_path));
 		prne_memzero(prne_s_g->upbin_args, sizeof(prne_s_g->upbin_args));
+		prne_g.shm_fd = fd;
+		fd = -1;
 	}
 
 END:
diff --git a/src/proone.h b/src/proone.h
index c45f0ae..1767016 100644
--- a/src/proone.h
+++ b/src/proone.h
@@ -1,3 +1,7 @@
+/** \file
+ * \brief The Proone instance process implementation header. This header
+ *	separates the structures and macros from proone.c for ease of maintenance.
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -35,47 +39,116 @@
 #include <mbedtls/entropy.h>
 #include <mbedtls/ctr_drbg.h>
 
-
+// The maximum number of the BNE worker instances.
 #define PROONE_BNE_MAX_CNT	128
 
-struct prne_global { // TODO: tidy init code when finalised
+// The process global resources.
+struct prne_global {
+	// The parent process start time(CLOCK_MONOTONIC)
 	struct timespec parent_start;
+	// The child process start time(CLOCK_MONOTONIC)
 	struct timespec child_start;
+	/**
+	 * \brief The boot uuid read off the platform.
+	 * \see random(4)
+	 */
 	uint8_t boot_id[16];
+	/**
+	 * \brief The instance id, an uuid randomly generated on the first parent
+	 * 	process initialisation. The id is preserved if shm is available on the
+	 *	host.
+	 * \see \c prne_shared_global
+	 */
 	uint8_t instance_id[16];
+	/**
+	 * \brief The main Pth thread handle obtained after the initialisation of
+	 *	the library for convenience. Upon initialisation, the main thread of the
+	 *	process becomes the "main pth thread". This handle never changes so
+	 *	Proone keeps it in the global to save CPU time on the function call to
+	 *	retrieve it every time it is required.
+	 */
 	pth_t main_pth;
-	/*
-	* Could be NULL. Just keep infecting other machines without it.
-	*/
+	/**
+	 * \brief (optional) The resolv worker. The Proone instance will operate
+	 *	without the worker if it fails to launch the worker. The services that
+	 *	depend on the resolv worker, the CNCP for example, will not be
+	 *	operational.
+	 */
 	prne_resolv_t *resolv;
-	pid_t parent_pid;
-	pid_t child_pid;
+	pid_t parent_pid; // The parent process id
+	pid_t child_pid; // The child process id obtained upon successful fork()
+	/**
+	 * \brief The "black hole" file descriptor is required by some workers(e.g
+	 *	the CNCP). The null device is usually used if available and falls back
+	 *	to the use of \c pipe() . The first element is only there to keep the
+	 *	pipe open in case \c pipe() is used. Use the second element for
+	 *	launching workers!
+	 * \note The workers do not actually try to write anything on the black hole
+	 *	file. The black hole file is only used to make \c poll() return
+	 *	immediately.
+	 * \see \c open_blackhole()
+	 */
 	int blackhole[2];
+	/**
+	 * \brief The backing file of the shared global. The file must be kept open
+	 *	to retain the lock on the file.
+	 * \see \c prne_shared_global()
+	 */
 	int shm_fd;
+	// The recombination parameter shared among the workers
 	prne_rcb_param_t rcb_param;
+	// The executable host info of the instance
 	prne_bin_host_t bin_host;
+	// The pointer to the data vault from the process image
 	uint8_t *m_dvault;
+	// True if the process is the child process
 	bool is_child;
+	/*
+	 * True if the process image contains the binary archive. The binary archive
+	 * is the largest portion of the data appended to the ELF. This flag will
+	 * come in handy when investigating incomplete transmission of binary data.
+	 * Note that you may run Proone without the ba for debugging purposes, but
+	 * you'd want to release Proone with the ba.
+	 */
 	bool has_ba;
+	// The bit flags for the htbt hostinfo request
 	uint8_t flags[prne_bf_get_size(NB_PRNE_IFLAG)];
 
+	/*
+	 * The indexed binary archive. The has_ba member can be used to determine if
+	 * the executable has an empty ba or no ba at all.
+	 */
 	prne_bin_archive_t bin_archive;
+	// The credential dictionary deserialised from the data vault
 	prne_cred_dict_t cred_dict;
 
+	// The objects for TLS
 	struct {
-		mbedtls_x509_crt ca;
+		mbedtls_x509_crt ca; // The CA cert chain
+		/**
+		 * \brief The entropy source. Note that Proone makes some modiifcations
+		 *	on the object to get around the issue associated with the platform
+		 *	entropy source.
+		 * \see \c prne_mbedtls_entropy_init()
+		 */
 		mbedtls_entropy_context entpy;
+		/*
+		 * The CTR_DRBG PRNG engine. Shared among the workers that require a
+		 * cryptographically-secure PRNG.
+		 */
 		mbedtls_ctr_drbg_context rnd;
 	} ssl;
+	// The TLS objects for listen sockets
 	struct {
-		bool ready;
+		bool ready; // True if the objects are successfully initialised for use
 		mbedtls_ssl_config conf;
 		mbedtls_x509_crt crt;
 		mbedtls_pk_context pk;
 		mbedtls_dhm_context dhm;
 	} s_ssl;
+	// The TLS objects for client connections
 	struct {
-		bool ready;
+		bool ready; // True if the objects are successfully initialised for use
 		mbedtls_ssl_config conf;
 		mbedtls_x509_crt crt;
 		mbedtls_pk_context pk;
@@ -83,24 +156,37 @@ struct prne_global { // TODO: tidy init code when finalised
 };
 
 struct prne_shared_global {
-	// Format Revision
-	uint8_t rev;
-	// Number of child process crash.
-	uint32_t crash_cnt;
-	// "break and entry" count. Number of successful logins.
+	uint8_t rev; // The format revision number
+	uint32_t crash_cnt; // The number of child process crash events
+	// "break and entry" count - the number of successful logins
 	uint64_t bne_cnt;
-	// Number of successful infections.
+	/*
+	 * The number of successful infections - the number of successful instance
+	 * launches
+	 */
 	uint64_t infect_cnt;
-	// null-terminated path to the new binary image
+	/*
+	 * The null-terminated path to the new process image downloaded from the
+	 * peer
+	 */
 	char upbin_path[256];
+	/**
+	 * \brief The arguments to exec() call, in the serialised form
+	 * \see \c prne_htbt_parse_args()
+	 */
 	char upbin_args[1024];
+	// The byte length of the contents of host_cred_data
 	size_t host_cred_len;
+	/**
+	 * \brief The host credential data of the instance, in the serialised form.
+	 * \see \c prne_dec_host_cred()
+	 */
 	uint8_t host_cred_data[255];
+	// The preserved instance id generated on the first instance launch
 	uint8_t instance_id[16];
+	/**
+	 * \brief The id of the instance infected the instance
+	 * \see /doc/htbt.md
+	 */
 	uint8_t org_id[16];
 };
-
-
-extern struct prne_global prne_g;
-// could be NULL on some environments
-extern struct prne_shared_global *prne_s_g;
diff --git a/src/protocol.c b/src/protocol.c
index 6cff4a5..0ea8038 100644
--- a/src/protocol.c
+++ b/src/protocol.c
@@ -1124,6 +1124,7 @@ char **prne_htbt_parse_args (
 	while (ptr < end) {
 		next = prne_strnchr(ptr, 0, end - ptr);
 		if (next == NULL) {
+			errno = EINVAL;
 			return NULL; // reject non-null-terminated
 		}
 		else {
@@ -1135,6 +1136,7 @@ char **prne_htbt_parse_args (
 	}
 	cnt += add_argc;
 	if (cnt > max_args) {
+		errno = E2BIG;
 		return NULL;
 	}
 
diff --git a/src/protocol.h b/src/protocol.h
index 600be8a..99fb198 100644
--- a/src/protocol.h
+++ b/src/protocol.h
@@ -1,3 +1,7 @@
+/** \file
+ * \brief The protocol header. All the facilities related to over-the-wire data
+ *	formats are defined here.
+ */
 /*
 * Copyright (c) 2019-2021 David Timber <mieabby@gmail.com>
 *
@@ -27,12 +31,24 @@
 #include <stdbool.h>
 
 #include <netinet/in.h>
-
+/** \def PRNE_PROONE_EC_OK PRNE_PROONE_EC_FAIL PRNE_PROONE_EC_LOCK
+ * \brief The exit codes.
+ */
+/* Graceful termination
+ * Note that the child process raises SIGTERM to serve executable upgrade
+ * request. In such case, the parent process tries exec(), not exit(0).
+ */
 #define PRNE_PROONE_EC_OK		0
+// General fatal failure. Generally the initialisation error.
 #define PRNE_PROONE_EC_FAIL		1
+/*
+ * The process could not continue because an instance is already running on the
+ * system.
+ */
 #define PRNE_PROONE_EC_LOCK		3
 
 
+/* Forward declarations */
 typedef struct prne_net_endpoint prne_net_endpoint_t;
 typedef struct prne_ip_addr prne_ip_addr_t;
 typedef struct prne_host_cred prne_host_cred_t;
@@ -45,511 +61,970 @@ typedef struct prne_htbt_hover prne_htbt_hover_t;
 typedef struct prne_htbt_stdio prne_htbt_stdio_t;
 typedef struct prne_htbt_rcb prne_htbt_rcb_t;
 
+// The OS codes
 typedef enum {
 	PRNE_OS_NONE,
 
-	PRNE_OS_LINUX,
+	PRNE_OS_LINUX, // Linux ABI
 
 	NB_PRNE_OS
 } prne_os_t;
 PRNE_LIMIT_ENUM(prne_os_t, NB_PRNE_OS, 0xFE);
 
+// The CPU architecture codes
 typedef enum {
-	PRNE_ARCH_NONE,
-
-	PRNE_ARCH_I686,
-	PRNE_ARCH_X86_64,
-	PRNE_ARCH_ARMV4T,
-	PRNE_ARCH_ARMV7,
-	PRNE_ARCH_AARCH64,
-	PRNE_ARCH_MIPS,
-	PRNE_ARCH_MPSL,
-	PRNE_ARCH_PPC,
-	PRNE_ARCH_SH4,
-	PRNE_ARCH_M68K,
-	PRNE_ARCH_ARC,
-	PRNE_ARCH_ARCEB,
-
-	NB_PRNE_ARCH
+	PRNE_ARCH_NONE, // The null value
+
+	PRNE_ARCH_I686, // Intel P6 microarchitecture (Pentium Pro)
+	PRNE_ARCH_X86_64, // AMD64 Opteron "SledgeHammer"
+	PRNE_ARCH_ARMV4T, // ARM v4 w/ MMU, Thumb (ARM920T)
+	PRNE_ARCH_ARMV7, // ARM v7 w/ MMU, Thumb-2, VFPv4 FPU (Cortex-A5)
+	PRNE_ARCH_AARCH64, // AArch64 (Cortex-A35)
+	PRNE_ARCH_MIPS, // MIPS 1 (R3000) running in big-endian mode
+	PRNE_ARCH_MPSL, // MIPS 1 (R3000) running in little-endian mode
+	PRNE_ARCH_PPC, // PowerPC 1
+	PRNE_ARCH_SH4, // Renesas SuperH 4
+	PRNE_ARCH_M68K, // Motorola 68040
+	PRNE_ARCH_ARC, // DesignWare ARC Processor running in little-endian mode
+	PRNE_ARCH_ARCEB, // DesignWare ARC Processor running in big-endian mode
+
+	NB_PRNE_ARCH // Meta value: the number of enums
 } prne_arch_t;
 PRNE_LIMIT_ENUM(prne_arch_t, NB_PRNE_ARCH, 0xFE);
 
 // Instance flags
 typedef enum {
-	PRNE_IFLAG_NONE = -1,
+	PRNE_IFLAG_NONE = -1, // The null value
 
-	PRNE_IFLAG_BA, // bin archive
-	PRNE_IFLAG_INIT_RUN, // initial run
-	PRNE_IFLAG_WKR_RCN,
-	PRNE_IFLAG_WKR_RESOLV,
-	PRNE_IFLAG_WKR_HTBT,
+	PRNE_IFLAG_BA, // The instance has ba.
+	// The instance has started for the first time on the host
+	PRNE_IFLAG_INIT_RUN,
+	PRNE_IFLAG_WKR_RCN, // The recon worker running.
+	PRNE_IFLAG_WKR_RESOLV, // The resolv worker running.
+	PRNE_IFLAG_WKR_HTBT, // The htbt worker running.
 
-	NB_PRNE_IFLAG
+	NB_PRNE_IFLAG // Meta value: the number of enums.
 } prne_iflag_t;
 
+// The internet protocol version
 typedef enum {
-	PRNE_IPV_NONE,
-	PRNE_IPV_4,
-	PRNE_IPV_6
+	PRNE_IPV_NONE, // The null value
+	PRNE_IPV_4, // The internet protocol version 4
+	PRNE_IPV_6 // The internet protocol version 6
 } prne_ipv_t;
 
+// IP header sanity check
 prne_static_assert(
 	sizeof(struct in_addr) == 4,
 	"sizeof(struct in_addr) == 4");
+// IP header sanity check
 prne_static_assert(
 	sizeof(struct in6_addr) == 16,
 	"sizeof(struct in6_addr) == 16");
+// The IP address object capable of storing an IP address of IPv4 and IPv6
 struct prne_ip_addr {
-	uint8_t addr[16];
-	prne_ipv_t ver;
-	uint32_t scope_id;
+	uint8_t addr[16]; // The address storage in the network order
+	prne_ipv_t ver; // The internet protocol version of the address
+	uint32_t scope_id; // The scope id used for IPv4
 };
 
+// The IP endpoint object used to describe a UDP or TCP over IP end-point
 struct prne_net_endpoint {
-	prne_ip_addr_t addr;
-	uint16_t port;
+	prne_ip_addr_t addr; // The IP address object
+	uint16_t port; // The port number in the host endian
 };
 
+// The host credential object
 struct prne_host_cred {
-	char *id;
-	char *pw;
+	char *id; // The null-terminated username string (dynamically allocated)
+	char *pw; // The null-terminated password string (dynamically allocated)
 };
 
-/* Heartbeat Frame OP Codes
-* All messages start with uint16_t 'msg_id', whose most significant bit is
-* used to indicate whether the message is a initiation(1) or a response(0).
-* 'msg_id' is a randomly generated by either end of connection. The value 0 is
-* only valid for `PRNE_HTBT_OP_NOOP`(so that NOOP message is either 23 or 24
-* zeroes over the wire).
-* 'msg_id' is followed by uint8_t 'op', which holds a `prne_htbt_op_t` value.
-* The length of data follows varies depending on 'op'.
-*/
+// The heartbeat framing protocol OP codes
 typedef enum {
-	PRNE_HTBT_OP_NONE = -1,
-
-	/* NOOP(keep-alive message): followed by nothing
-	*/
-	PRNE_HTBT_OP_NOOP,
-	/* Operation Status
-	* Followed by:
-	* 	uint8_t code: prne_htbt_status_t
-	* 	int32_t err: errno value(used for `PRNE_HTBT_STATUS_ERRNO`)
-	*/
-	PRNE_HTBT_OP_STATUS,
-	/* Host Info Operation: followed by nothing
-	*
-	* The submissive end's response format:
-	* 	uint8_t prog_ver[16]
-	* 	uint8_t boot_id[16]
-	* 	uint8_t instance_id[16]
-	* 	uint8_t org_id[16]
-	* 	uint32_t parent_uptime	: in seconds
-	* 	uint32_t child_uptime	: in seconds
-	* 	uint64_t bne_cnt		: break-and-entry count
-	* 	uint64_t infect_cnt		: infect count ( <= 'bne_cnt')
-	*	uint32_t crash_cnt
-	* 	uint32_t parent_pid
-	* 	uint32_t child_pid
-	* 	uint8_t host_cred_len
-	* 	uint8_t arch			: `prne_arch_t` value
-	* 	uint8_t os
-	* 	uint8_t bf_len
-	* 	uint8_t host_cred[host_cred_len]
-	* 	uint8_t bf[bf_len]
-	*/
-	PRNE_HTBT_OP_HOST_INFO,
-	/* Hand Over Operation
-	* Upon reception of message, the submissive end should conclude
-	* the connection and get further instruction(op) from the host
-	* described in the message.
-	*
-	* Followed by:
-	* 	uint8_t addr_4[4]
-	* 	uint16_t port_4
-	* 	uint8_t addr_6[16]
-	* 	uint16_t port_6
-	*/
-	PRNE_HTBT_OP_HOVER,
-	/* OP Solicit Operation: followed by nothing
-	* This op is used by the submissive end to solicit instruction(op) from
-	* the authoritive end. This op is used when the submissive end has
-	* connected to the authoritive end after having been instructed by
-	* the previous authoritive end(PRNE_HTBT_OP_HOVER).
-	*/
-	PRNE_HTBT_OP_SOLICIT,
-	/* Run Command Operation
-	* TODO
-	*
-	* Followed by
-	*	uint5_t rsv
-	*	uint1_t detach
-	* 	uint10_t args_len	: the length of 'args'
-	* 	char args[len]		: the series of null-terminated string for exec*()
-	*/
-	PRNE_HTBT_OP_RUN_CMD,
-	/* Binary Upgrade Operation
-	* TODO
-	*
-	* Followed by:
-	* 	uint24_t alloc_len
-	*	uint5_t rsv
-	*	uint1_t detach
-	* 	uint10_t args_len
-	* 	char args[args_len]
-	*/
-	PRNE_HTBT_OP_UP_BIN,
-	/* Run Binary Operation
-	* TODO
-	*
-	* Followed by:
-	* 	uint24_t alloc_len
-	*	uint5_t rsv
-	*	uint1_t detach
-	* 	uint10_t args_len
-	* 	char args[args_len]
-	*/
-	PRNE_HTBT_OP_RUN_BIN,
-	/* STDIO Frame
-	* TODO
-	*
-	*	uint1_t err		: 0 - stdin/stdout, 1 - stderr
-	*	uint1_t fin
-	*	uint2_t rsv
-	*	uint12_t len
-	*/
-	PRNE_HTBT_OP_STDIO,
-	/* Binary Recombination Operation
-	* TODO
-	*
-	*	uint1_t compat	: allow fallback to compatible arch
-	*	uint1_t self	: os and arch not used if true
-	*	uint6_t rsv
-	*	uint8_t os
-	*	uint8_t arch
-	*/
-	PRNE_HTBT_OP_RCB,
-
-	NB_PRNE_HTBT_OP
+	PRNE_HTBT_OP_NONE = -1, // The null value
+
+	PRNE_HTBT_OP_NOOP, // No operation
+	PRNE_HTBT_OP_STATUS, // Status operation
+	PRNE_HTBT_OP_HOST_INFO, // Host info operation
+	PRNE_HTBT_OP_HOVER, // Hand-over operation
+	PRNE_HTBT_OP_SOLICIT, // Solicit operation
+	PRNE_HTBT_OP_RUN_CMD, // Execute operation
+	PRNE_HTBT_OP_UP_BIN, // Binary upgrade operation
+	PRNE_HTBT_OP_RUN_BIN, // Execute binary operation
+	PRNE_HTBT_OP_STDIO, // STDIO frame
+	PRNE_HTBT_OP_RCB, // Binary recombination operation
+
+	NB_PRNE_HTBT_OP // Meta value: the number of enums
 } prne_htbt_op_t;
 PRNE_LIMIT_ENUM(prne_htbt_op_t, NB_PRNE_HTBT_OP, 0xFE);
 
+// The heartbeat framing protocol status codes
 typedef enum {
-	PRNE_HTBT_STATUS_OK,
-	PRNE_HTBT_STATUS_UNIMPL,
-	/* Protocol error detected. Mosts likely a format error.
-	* An int32_t that follows is not used.
-	*/
-	PRNE_HTBT_STATUS_PROTO_ERR,
-	/* An internal error occurred whilst processing request.
-	* Followed by int32_t which represents the errno set during the operation.
-	*/
-	PRNE_HTBT_STATUS_ERRNO,
-	PRNE_HTBT_STATUS_SUB,
-	PRNE_HTBT_STATUS_LIMIT,
-
-	NB_PRNE_HTBT_STATUS
+	PRNE_HTBT_STATUS_OK, // Operation successful
+	PRNE_HTBT_STATUS_UNIMPL, // Function not implemented
+	PRNE_HTBT_STATUS_PROTO_ERR, // Protocol error
+	PRNE_HTBT_STATUS_ERRNO, // errno set
+	PRNE_HTBT_STATUS_SUB, // Error returned from module
+	PRNE_HTBT_STATUS_LIMIT, // Limit reached
+
+	NB_PRNE_HTBT_STATUS // Meta value: the number of enums
 } prne_htbt_status_code_t;
 PRNE_LIMIT_ENUM(prne_htbt_status_code_t, NB_PRNE_HTBT_STATUS, 0xFF);
 
+// The heartbeat framing protocol (de)serialisaion function result codes
 typedef enum {
-	PRNE_HTBT_SER_RC_OK,
+	PRNE_HTBT_SER_RC_OK, // Success
+	// More input data required or more output buffer required
 	PRNE_HTBT_SER_RC_MORE_BUF,
-	PRNE_HTBT_SER_RC_ERRNO,
-	PRNE_HTBT_SER_RC_FMT_ERR,
+	PRNE_HTBT_SER_RC_ERRNO, // errno set
+	PRNE_HTBT_SER_RC_FMT_ERR, // Input data format error
 
-	NB_PRNE_HTBT_SER_RC
-} prne_htbt_ser_rc_t; // serialise result code
+	NB_PRNE_HTBT_SER_RC // Meta value: the number of enums
+} prne_htbt_ser_rc_t;
 
+// The heartbeat framing protocol message header frame
 struct prne_htbt_msg_head {
-	prne_htbt_op_t op;
-	uint16_t id; // != 0 (except NOOP)
-	bool is_rsp;
+	prne_htbt_op_t op; // The OP code
+	uint16_t id; // The message id
+	bool is_rsp; // The response flag
 };
 
+// The heartbeat framing protocol status frame
 struct prne_htbt_status {
-	prne_htbt_status_code_t code;
-	int32_t err;
+	prne_htbt_status_code_t code; // The status code
+	int32_t err; // The sub-status code
 };
 
+// The heartbeat framing protocol hostinfo frame
 struct prne_htbt_host_info {
-	uint32_t parent_uptime;
-	uint32_t child_uptime;
-	uint64_t bne_cnt;
-	uint64_t infect_cnt;
-	uint32_t parent_pid;
-	uint32_t child_pid;
-	uint8_t prog_ver[16];
-	uint8_t boot_id[16];
-	uint8_t instance_id[16];
-	uint8_t org_id[16];
-	uint8_t *host_cred;
-	size_t host_cred_len;
-	size_t bf_len;
-	uint8_t *bf;
-	uint32_t crash_cnt;
-	prne_arch_t arch;
-	prne_os_t os;
+	uint32_t parent_uptime; // The parent process uptime in seconds
+	uint32_t child_uptime; // The child process uptime in seconds
+	uint64_t bne_cnt; // The "break and entry" count
+	uint64_t infect_cnt; // The infect count
+	uint32_t parent_pid; // The parent process id
+	uint32_t child_pid; // The child process id
+	uint8_t prog_ver[16]; // The program version uuid
+	uint8_t boot_id[16]; // The boot uuid
+	uint8_t instance_id[16]; // The instance uuid
+	uint8_t org_id[16]; // The instance uuid of the instance infected the host
+	uint8_t *host_cred; // The host credential data
+	size_t host_cred_len; // The byte length of the host credential data
+	size_t bf_len; // The byte length of the diagnostic bit field
+	uint8_t *bf; // The diagnostic bit field
+	uint32_t crash_cnt; // The crash count
+	prne_arch_t arch; // The CPU architecture code of the host
+	prne_os_t os; // The OS code of the host
 };
 
+// The heartbeat framing protocol command frame
 struct prne_htbt_cmd {
-	char *mem;
-	size_t mem_len;
-	char **args;
-	uint8_t argc;
-	bool detach;
+	char *mem; // The linear memory for storing the argument vector
+	size_t mem_len; // The byte length of the linear memory
+	char **args; // The array of pointers to the strings in the linear memory
+	uint8_t argc; // The number of elements in the array
+	bool detach; // The detach flag
 };
 
+/*
+ * The heartbeat framing protocol binary meta frame - extension of the command
+ * frame
+ */
 struct prne_htbt_bin_meta {
-	size_t alloc_len;
-	prne_htbt_cmd_t cmd;
+	size_t alloc_len; // The advisory file preallocation byte length
+	prne_htbt_cmd_t cmd; // The command frame
 };
 
+// The heartbeat framing protocol hand-over frame
 struct prne_htbt_hover {
+	// The IPv4 end-point info
 	struct {
-		uint8_t addr[4];
-		uint16_t port;
+		uint8_t addr[4]; // The address in the network order
+		uint16_t port; // The port number in the host endian
 	} v4;
+	// The IPv6 end-point info
 	struct {
-		uint8_t addr[16];
-		uint16_t port;
+		uint8_t addr[16]; // The address in the network order
+		uint16_t port; // The port number in the host endian
 	} v6;
 };
 
+// The heartbeat framing protocol STDIO frame
 struct prne_htbt_stdio {
-	size_t len;
-	bool err;
-	bool fin;
+	size_t len; // The byte length of the data
+	bool err; // The standard error stream flag
+	bool fin; // The final data flag
 };
 
+// The heartbeat protocol binary RCB frame
 struct prne_htbt_rcb {
-	prne_os_t os;
-	prne_arch_t arch;
-	bool compat;
-	bool self;
+	prne_os_t os; // The OS code
+	prne_arch_t arch; // The CPU architecture code
+	bool compat; // The allow-compatible-arch flag
+	bool self; // The perform-self-copy flag
 };
 
+/*
+ * The standard function pointer type of the heartbeat framing protocol frame
+ * initialisation functions.
+ */
 typedef void(*prne_htbt_init_ft)(void *ptr);
+/*
+ * The standard function pointer type of the heartbeat framing protocol frame
+ * deinitialisation functions.
+ */
 typedef void(*prne_htbt_free_ft)(void *ptr);
+/*
+ * The standard function pointer type of the heartbeat framing protocol frame
+ * equality operator functions.
+ */
 typedef bool(*prne_htbt_eq_ft)(const void *a, const void *b);
+/*
+ * The standard function pointer type of the heartbeat framing protocol frame
+ * serialisation functions.
+ */
 typedef prne_htbt_ser_rc_t(*prne_htbt_ser_ft)(
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const void *in);
+/*
+ * The standard function pointer type of the heartbeat framing protocol frame
+ * deserialisation functions.
+ */
 typedef prne_htbt_ser_rc_t(*prne_htbt_dser_ft)(
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	void *out);
 
+// The heartbeat framing protocol TLS ALP string
 #define PRNE_HTBT_TLS_ALP			"prne-htbt"
+// The heartbeat framing protocol minimum valid message id
 #define PRNE_HTBT_MSG_ID_MIN		1
+// The heartbeat framing protocol message id min-max delta
 #define PRNE_HTBT_MSG_ID_DELTA		(INT16_MAX - 1)
+// The heartbeat framing protocol message id reserved for notification
 #define PRNE_HTBT_MSG_ID_NOTIFY		INT16_MAX
+// The heartbeat framing protocol standard TCP/IP port
 #define PRNE_HTBT_PROTO_PORT		64420
-// _POSIX_ARG_MAX equiv
+/*
+ * The heartbeat framing protocol maximum number of arguments in the command
+ * frame. The _POSIX_ARG_MAX equivalent.
+ */
 #define PRNE_HTBT_ARGS_MAX			255
+/*
+ * The heartbeat framing protocol maximum byte length of the linear memory of
+ * the command frame
+ */
 #define PRNE_HTBT_ARG_MEM_MAX		1023
+// The heartbeat framing protocol maximum byte length of STDIO data per frame
 #define PRNE_HTBT_STDIO_LEN_MAX		0x0FFF
+/* The heartbeat framing protocol maximum possible value for the advisory file
+ * preallocation byte length. This value actually means "the length of the file
+ * is more than 16,777,215 bytes".
+ */
 #define PRNE_HTBT_BIN_ALLOC_LEN_MAX	0xFFFFFF
 
-/* PRNE_HTBT_PROTO_MIN_BUF
-*
-* Minimum size of buffer required to implement parsing of stream. This is the
-* size required to deserialise PRNE_HTBT_OP_UP_BIN and PRNE_HTBT_OP_RUN_BIN.
-*/
+/*
+ * The bare minimum byte size of buffer required to parse the heartbeat framing
+ * protocol stream. Currently set to the size of buffer required to parse
+ * PRNE_HTBT_OP_RUN_BIN.
+ */
 #define PRNE_HTBT_PROTO_MIN_BUF ((size_t)3 + 5 + PRNE_HTBT_ARG_MEM_MAX)
-/* PRNE_HTBT_PROTO_SUB_MIN_BUF
-*
-* Required write buffer size for submissive end. Set to that of
-* PRNE_HTBT_OP_HOST_INFO.
-*/
+/*
+ * The bare minimum byte size of buffer required for a submissive host to send
+ * the heartbeat framing protocol frame. Currently set to the size of buffer
+ * required to send PRNE_HTBT_OP_HOST_INFO.
+ */
 #define PRNE_HTBT_PROTO_SUB_MIN_BUF ((size_t)3 + 104 + 255 + 255)
 
 
+/**
+ * \brief Convert the enum value to a string, which can be converted back to the
+ *	original enum value.
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
 const char *prne_os_tostr (const prne_os_t x);
+/**
+ * \brief Convert the string to the enum value.
+ * \return The enum value.
+ * \retval \c PRNE_OS_NONE if the string does not match any of the enums and
+ *	\c errno set to \c EINVAL
+ * \note The function accepts NULL.
+ */
 prne_os_t prne_os_fstr (const char *str);
+/**
+ * \brief Test if the enum value is in range
+ * \retval true if the enum value is in range
+ * \return false otherwise
+ */
 bool prne_os_inrange (const prne_os_t x);
+/**
+ * \brief Convert the enum value to a string, which can be converted back to the
+ *	original enum value.
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
 const char *prne_arch_tostr (const prne_arch_t x);
+/**
+ * \brief Convert the string to the enum value.
+ * \return The enum value.
+ * \retval \c PRNE_ARCH_NONE if the string does not match any of the enums and
+ *	\c errno set to \c EINVAL
+ * \note The function accepts NULL.
+ */
 prne_arch_t prne_arch_fstr (const char *str);
+/**
+ * \brief Test if the enum value is in range
+ * \retval true if the enum value is in range
+ * \return false otherwise
+ */
 bool prne_arch_inrange (const prne_arch_t x);
+/**
+ * \brief Convert the enum value to a string, which can be converted back to the
+ *	original enum value.
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
 const char *prne_iflag_tostr (const prne_iflag_t x);
+/**
+ * \brief Convert the string to the enum value.
+ * \return The enum value.
+ * \retval \c PRNE_IFLAG_NONE if the string does not match any of the enums and
+ *	\c errno set to \c EINVAL
+ * \note The function accepts NULL.
+ */
 prne_iflag_t prne_iflag_fstr (const char *str);
+/**
+ * \brief Test if the enum value is in range
+ * \retval true if the enum value is in range
+ * \return false otherwise
+ */
 bool prne_iflag_inrange (const prne_iflag_t x);
 
+/**
+ * \brief The equality operator of
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_eq_ipaddr (const prne_ip_addr_t *a, const prne_ip_addr_t *b);
+/**
+ * \brief Convert the IP endpoint object to \c sockaddr_in
+ */
 void prne_net_ep_tosin4 (
 	const prne_net_endpoint_t *ep,
 	struct sockaddr_in *out);
+/**
+ * \brief Convert the IP endpoint object to \c sockaddr_in6
+ */
 void prne_net_ep_tosin6 (
 	const prne_net_endpoint_t *ep,
 	struct sockaddr_in6 *out);
+/**
+ * \brief (unused)
+ */
 bool prne_net_ep_set_ipv4 (
 	const char *str,
 	const uint16_t port,
 	prne_net_endpoint_t *out);
+/**
+ * \brief (unused)
+ */
 bool prne_net_ep_set_ipv6 (
 	const char *str,
 	const uint16_t port,
 	prne_net_endpoint_t *out);
 
+/**
+ * \brief Convert the enum value to a string
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
 const char *prne_htbt_op_tostr (const prne_htbt_op_t x);
 
+/**
+ * \brief Initialise the heartbeat framing protocol message header frame
+ * \note Initialises the members of \p mh to initial values. Prepares \p mh so
+ * 	that it can be freed using \c prne_htbt_free_msg_head()
+ */
 void prne_htbt_init_msg_head (prne_htbt_msg_head_t *mh);
+/**
+ * \brief Free the resources allocated for the heartbeat framing protocol
+ *	message header frame
+ * \param mh The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_msg_head()
+ */
 void prne_htbt_free_msg_head (prne_htbt_msg_head_t *mh);
+/**
+ * \brief The equality operator of the heartbeat framing protocol message header
+ *	frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_msg_head (
 	const prne_htbt_msg_head_t *a,
 	const prne_htbt_msg_head_t *b);
 
+/**
+ * \brief Initialise the heartbeat framing protocol status frame
+ * \note Initialises the members of \p s to initial values. Prepares \p s so
+ * 	that it can be freed using \c prne_htbt_free_status()
+ */
 void prne_htbt_init_status (prne_htbt_status_t *s);
+/**
+ * \brief Free the resources allocated for the heartbeat framing protocol status
+ *	frame
+ * \param s The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_status()
+ */
 void prne_htbt_free_status (prne_htbt_status_t *s);
+/**
+ * \brief The equality operator of the heartbeat framing protocol status frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_status (
 	const prne_htbt_status_t *a,
 	const prne_htbt_status_t *b);
 
+/**
+ * \brief Initialise the host credential object
+ * \note Initialises the members of \p hc to initial values. Prepares \p hc so
+ * 	that it can be freed using \c prne_free_host_cred()
+ */
 void prne_init_host_cred (prne_host_cred_t *hc);
+/**
+ * \brief Allocate dynamic memory for the members to hold credential data
+ * \param hc The pointer to the host credential object
+ * \param id_len The length of the username string
+ * \param pw_len The length of the password string
+ * \return true if allocation was successful
+ * \return false if allocation failed and \c errno is set to \c ENOMEM
+ * \note The object is modified only when allocation is successful. In case of
+ *	failure, you may continue to use the object without reinitialisation. The
+ *	dynamically allocated members are freed prior to being assigned with new
+ *	memory.
+ */
 bool prne_alloc_host_cred (
 	prne_host_cred_t *hc,
 	const uint8_t id_len,
 	const uint8_t pw_len);
+/**
+ * \brief Free the resources allocated for the host credential object
+ * \param hc The pointer to the object that has been initialised using
+ * 	\c prne_init_host_cred()
+ */
 void prne_free_host_cred (prne_host_cred_t *hc);
+/**
+ * \brief The equality operator of the host credential object
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_eq_host_cred (const prne_host_cred_t *a, const prne_host_cred_t *b);
+/**
+ * \brief Serialise the host credential object
+ * \param[out] data The output buffer
+ * \param len The available byte length of the buffer
+ * \param[out] actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if more than 255 bytes are required for the
+ *	result binary data.
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if larger buffer is required.
+ * \retval PRNE_HTBT_SER_RC_OK if successful.
+ * \note Note that the byte length of binary data is limited to 255 because the
+ *	format is designed for the heartbeat framing protocol hostinfo frame.
+ */
 prne_htbt_ser_rc_t prne_enc_host_cred (
 	uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	const prne_host_cred_t *in);
+/**
+ * \brief Deserialise the host credential object from the binary data
+ * \param data The binary data
+ * \param len The byte length of the binary data available for reading
+ * \param out The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR on parsing error.
+ * \retval PRNE_HTBT_SER_RC_ERRNO on \c ENOMEM
+ * \retval PRNE_HTBT_SER_RC_OK if successful
+ * \warning The parsed strings must be treated as binary data until proven
+ *	otherwise using \c isprint() equiavalent for your need. The code page and
+ *	character encoding are outside of the scope of the protocol.
+ */
 prne_htbt_ser_rc_t prne_dec_host_cred (
 	const uint8_t *data,
 	const size_t len,
 	prne_host_cred_t *out);
 
+/**
+ * \brief Initialise the heartbeat framing protocol hostinfo frame
+ * \note Initialises the members of \p hi to initial values. Prepares \p hi so
+ * 	that it can be freed using \c prne_htbt_free_host_info()
+ */
 void prne_htbt_init_host_info (prne_htbt_host_info_t *hi);
+/**
+ * \brief Allocate variable-length members of the heartbeat framing protocol
+ *	hostinfo frame
+ * \param hi The pointer to the object
+ * \param cred_len The byte length required for the host credential data
+ * \param bf_len The byte length required for the bit field data
+ * \return true if allocation was successful
+ * \return false on failure and \c errno set to \c ENOMEM
+ */
 bool prne_htbt_alloc_host_info (
 	prne_htbt_host_info_t *hi,
 	const size_t cred_len,
 	const size_t bf_len);
+/**
+ * \brief Free the resources allocated for the heartbeat framing protocol
+ *	hostinfo frame
+ * \param hi The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_host_info()
+ */
 void prne_htbt_free_host_info (prne_htbt_host_info_t *hi);
+/**
+ * \brief The equality operator of the heartbeat framing protocol hostinfo frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_host_info (
 	const prne_htbt_host_info_t *a,
 	const prne_htbt_host_info_t *b);
 
+/**
+ * \brief Initialise the heartbeat framing protocol command frame
+ * \note Initialises the members of \p cmd to initial values. Prepares \p cmd so
+ * 	that it can be freed using \c prne_htbt_free_cmd()
+ */
 void prne_htbt_init_cmd (prne_htbt_cmd_t *cmd);
+/**
+ * \brief Allocate variable-length members of the heartbeat framing protocol
+ *	command frame
+ * \param cmd The pointer to the object
+ * \param argc The number of elements in the argument vector
+ * \param args_len The pointer to the array containing lengths of string for
+ *	each argument
+ * \return true if allocation was successful
+ * \return false on failure and \c errno set to \c ENOMEM
+ */
 bool prne_htbt_alloc_cmd (
 	prne_htbt_cmd_t *cmd,
 	const size_t argc,
 	const size_t *args_len);
 bool prne_htbt_set_cmd (prne_htbt_cmd_t *cmd, const char **args);
+/**
+ * \brief Free the resources allocated for the heartbeat framing protocol
+ *	command frame
+ * \param cmd The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_cmd()
+ */
 void prne_htbt_free_cmd (prne_htbt_cmd_t *cmd);
+/**
+ * \brief The equality operator of the heartbeat framing protocol command frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_cmd (const prne_htbt_cmd_t *a, const prne_htbt_cmd_t *b);
 
+/**
+ * \brief Initialise the heartbeat framing protocol binary meta frame
+ * \note Initialises the members of \p nb to initial values. Prepares \p nb so
+ * 	that it can be freed using \c prne_htbt_free_bin_meta()
+ */
 void prne_htbt_init_bin_meta (prne_htbt_bin_meta_t *nb);
+/**
+ * \brief Free the resources allocated for the the heartbeat framing protocol
+ * 	binary meta frame
+ * \param nb The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_bin_meta()
+ */
 void prne_htbt_free_bin_meta (prne_htbt_bin_meta_t *nb);
+/**
+ * \brief The equality operator of the heartbeat framing protocol binary meta
+ * 	frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_bin_meta (
 	const prne_htbt_bin_meta_t *a,
 	const prne_htbt_bin_meta_t *b);
 
+/**
+ * \brief Initialise the heartbeat framing protocol hand-over frame
+ * \note Initialises the members of \p ho to initial values. Prepares \p ho so
+ * 	that it can be freed using \c prne_htbt_free_hover()
+ */
 void prne_htbt_init_hover (prne_htbt_hover_t *ho);
+/**
+ * \brief Free the resources allocated for the heartbeat framing protocol
+ * 	hand-over frame
+ * \param ho The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_hover()
+ */
 void prne_htbt_free_hover (prne_htbt_hover_t *ho);
+/**
+ * \brief The equality operator of the heartbeat framing protocol hand-over
+ * 	frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_hover (
 	const prne_htbt_hover_t *a,
 	const prne_htbt_hover_t *b);
+/**
+ * \brief The deep copy operator of the heartbeat framing protocol hand-over
+ * 	frame
+ * \retval true if the contents of \p src have been successfully copied into
+ * 	\p dst
+ * \retval false otherwise and \c errno set
+ */
 bool prne_htbt_cp_hover (
-	const prne_htbt_hover_t *a,
-	prne_htbt_hover_t *b);
+	const prne_htbt_hover_t *src,
+	prne_htbt_hover_t *dst);
 
+/**
+ * \brief Initialise the heartbeat framing protocol STDIO frame
+ * \note Initialises the members of \p s to initial values. Prepares \p s so
+ * 	that it can be freed using \c prne_htbt_free_stdio()
+ */
 void prne_htbt_init_stdio (prne_htbt_stdio_t *s);
+/**
+ * \brief Free the resources allocated for the heartbeat framing protocol STDIO
+ * 	frame
+ * \param s The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_stdio()
+ */
 void prne_htbt_free_stdio (prne_htbt_stdio_t *s);
+/**
+ * \brief The equality operator of the heartbeat framing protocol STDIO frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_stdio (
 	const prne_htbt_stdio_t *a,
 	const prne_htbt_stdio_t *b);
 
+/**
+ * \brief Initialise the heartbeat protocol binary RCB frame
+ * \note Initialises the members of \p r to initial values. Prepares \p r so
+ * 	that it can be freed using \c prne_htbt_free_rcb()
+ */
 void prne_htbt_init_rcb (prne_htbt_rcb_t *r);
+/**
+ * \brief Free the resources allocated for the heartbeat protocol binary RCB
+ * 	frame
+ * \param r The pointer to the object that has been initialised using
+ * 	\c prne_htbt_init_rcb()
+ */
 void prne_htbt_free_rcb (prne_htbt_rcb_t *r);
+/**
+ * \brief The equality operator of the heartbeat protocol binary RCB frame
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
 bool prne_htbt_eq_rcb (const prne_htbt_rcb_t *a, const prne_htbt_rcb_t *b);
 
+/**
+ * \brief The serialisation function for the heartbeat framing protocol message
+ * 	header frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_msg_head (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_msg_head_t *in);
+/**
+ * \brief The serialisation function for the heartbeat framing protocol status
+ * 	frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_status (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_status_t *in);
+/**
+ * \brief The serialisation function for the heartbeat framing protocol hostinfo
+ * 	frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_host_info (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_host_info_t *in);
+/**
+ * \brief The serialisation function for the heartbeat framing protocol
+ * 	hand-over frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_hover (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_hover_t *in);
+/**
+ * \brief The serialisation function for the heartbeat framing protocol command
+ * 	frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_cmd (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_cmd_t *in);
+/**
+ * \brief The serialisation function for the heartbeat framing protocol binary
+ * 	meta frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_bin_meta (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_bin_meta_t *in);
+/**
+ * \brief The serialisation function for the heartbeat framing protocol STDIO
+ * 	frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_stdio (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_stdio_t *in);
+/**
+ * \brief The serialisation function for the heartbeat protocol binary RCB frame
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_ser_rcb (
 	uint8_t *mem,
 	const size_t mem_len,
 	size_t *actual,
 	const prne_htbt_rcb_t *in);
 
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol
+ * 	message header frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_msg_head (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_msg_head_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol status
+ * 	frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_status (
 	uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_status_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol
+ * 	hostinfo frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_host_info (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_host_info_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol
+ * 	hand-over frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_hover (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_hover_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol
+ * 	command frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_cmd (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_cmd_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol binary
+ * 	meta frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_bin_meta (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_bin_meta_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat framing protocol STDIO
+ * 	frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_stdio (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_stdio_t *out);
+/**
+ * \brief The deserialisation function for the heartbeat protocol binary RCB
+ * 	frame
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
 prne_htbt_ser_rc_t prne_htbt_dser_rcb (
 	const uint8_t *data,
 	const size_t len,
 	size_t *actual,
 	prne_htbt_rcb_t *out);
 
+/**
+ * \brief Index the series of strings to create an argument vector
+ * \param m_args The pointer to the series of strings
+ * \param args_size The byte length of the buffer
+ * \param add_argc The additional argument vector to prepend to the output
+ * 	argument vector
+ * \param add_args The number of elements in the additional argument vector
+ * \param[out] argc The number of elements in the output argument vector
+ * 	(optional)
+ * \param max_args The maximum number of elements allowed in the output argument
+ * 	vector. Use \c SIZE_MAX to disable this.
+ * \return The fabricated NULL element terminated argument vector, which can be
+ * 	passed directly to \c exec() Memory freeable with \c prne_free()
+ * \retval NULL and \c errno set to \c EINVAL - a null-terminator is not found
+ * 	at the end of \p m_args
+ * \retval NULL and \c errno set to \c E2BIG - the limit set with \p max_args
+ * 	reached.
+ * \retval NULL and \c errno set to \c ENOMEM - memory allocation for the ouput
+ * 	argument vector failed
+ * \note The function is used to prepare the argument vector for \c exec() call.
+ * 	The protocol is only responsible for the parametres and determining the file
+ * 	name of the executable is up to the implementation. The function is for
+ * 	parsing the linear argument vector from the heartbeat framing protocol
+ * 	command frame and prepending the path of the executable.
+ * \see \c exec()
+ */
 char **prne_htbt_parse_args (
 	char *m_args,
 	const size_t args_size,
@@ -558,6 +1033,20 @@ char **prne_htbt_parse_args (
 	size_t *argc,
 	const size_t max_args);
 
+/**
+ * \brief Generate an integer for a new heartbeat framing protocol session
+ * \param ctx The context object
+ * \param rnd_f The PRNG callback function
+ * \return A randomly generated unsigned 16-bit integer for a new session
+ * \note This function is a convenience function for clamping the randomly
+ * 	generated number into the range used by the protocol -
+ * 	[ \c PRNE_HTBT_MSG_ID_MIN , \c PRNE_HTBT_MSG_ID_DELTA )
+ */
 uint16_t prne_htbt_gen_msgid (void *ctx, uint16_t(*rnd_f)(void*));
 
+/**
+ * \brief Convert the enum value to a string
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
 const char *prne_htbt_serrc_tostr (const prne_htbt_ser_rc_t x);
diff --git a/templates/doxygen b/templates/doxygen
new file mode 100644
index 0000000..7129842
--- /dev/null
+++ b/templates/doxygen
@@ -0,0 +1,64 @@
+/**
+ * \brief Convert the enum value to a string
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
+/**
+ * \brief Convert the enum value to a string, which can be converted back to the
+ *	original enum value.
+ * \return The pointer to the string from the read-only static string pool.
+ * \retval NULL if \p x is out of bounds and \c errno set to \c EINVAL
+ */
+
+/**
+ * \brief Initialise the
+ * \note Initialises the members of \p x to initial values. Prepares \p x so
+ * 	that it can be freed using \c ff()
+ */
+/**
+ * \brief Free the resources allocated for the
+ * \param x The pointer to the object that has been initialised using
+ * 	\c if()
+ */
+
+/**
+ * \brief The equality operator of the
+ * \retval true if the contents of both \p a and \p b are identical
+ * \retval false otherwise
+ */
+/**
+ * \brief The deep copy operator of the
+ * \retval true if the contents of \p src have been successfully copied into
+ * 	\p dst
+ * \retval false otherwise and \c errno set
+ */
+/**
+ * \brief Allocate variable-length members of the
+ * \param x The pointer to the object
+ * \param x The byte length required for the
+ * \return true if allocation was successful
+ * \return false on failure and \c errno set to \c ENOMEM
+ */
+
+/**
+ * \brief The serialisation function for the
+ * \param mem The output buffer
+ * \param mem_len The byte length of the buffer available
+ * \param actual The actual number of bytes required or written
+ * \param in The pointer to the object
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more buffer is required for output
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */
+/**
+ * \brief The deserialisation function for the
+ * \param data The input binary data
+ * \param len The byte length of the input binary data
+ * \param actual The actual number of bytes processed or required
+ * \param out The pointer to the object for output
+ * \retval PRNE_HTBT_SER_RC_OK on success
+ * \retval PRNE_HTBT_SER_RC_MORE_BUF if more input data is required for parsing
+ * \retval PRNE_HTBT_SER_RC_ERRNO if an error occurred during the process
+ * \retval PRNE_HTBT_SER_RC_FMT_ERR if a format error encountered
+ */