Documentation (using Doxygen).

.github/workflows/documentation.yml

@@ -0,0 +1,37 @@
+name: Documentation
+
+# Controls when the action will run. Triggers the workflow on push or pull request
+# events but only for the master branch
+on:
+  push:
+    branches: [ feature/documentation ]
+  pull_request:
+    branches: [ feature/documentation ]
+
+
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+    - uses: actions/checkout@v2
+
+    - name: Doxygen Action
+      uses: mattnotmitt/[email protected]
+      with:
+        # Path to Doxyfile
+        doxyfile-path: "./doxygen.config" # default is ./Doxyfile
+        # Working directory
+        working-directory: "." # default is .
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./doc/html

lib/core/jbackend-operation.c

@@ -158,6 +158,7 @@ j_backend_operation_to_message(JMessage* message, JBackendOperationParam* data,
 	guint tmp;
 	GError** error;
 
+	// The following for-loop deduces the size of the memory (or bytes) that are required to write the provided operation(s).
 	for (i = 0; i < arrlen; i++)
 	{
 		len += 4;
@@ -206,11 +207,11 @@ j_backend_operation_to_message(JMessage* message, JBackendOperationParam* data,
 		}
 		len += element->len;
 	}
-	j_message_add_operation(message, len);
+	j_message_add_operation(message, len); // Extended the message's memory to write the new elements to it.
 	for (i = 0; i < arrlen; i++)
 	{
 		element = &data[i];
-		j_message_append_4(message, &element->len);
+		j_message_append_4(message, &element->len); // Writes (4 bytes) length of the element.
 		if (element->len)
 		{
 			switch (element->type)
@@ -219,13 +220,13 @@ j_backend_operation_to_message(JMessage* message, JBackendOperationParam* data,
 				case J_BACKEND_OPERATION_PARAM_TYPE_BLOB:
 					if (element->ptr)
 					{
-						j_message_append_n(message, element->ptr, element->len);
+						j_message_append_n(message, element->ptr, element->len); // Writes stream of given length.
 					}
 					break;
 				case J_BACKEND_OPERATION_PARAM_TYPE_BSON:
 					if (element->bson_initialized && element->ptr)
 					{
-						j_message_append_n(message, bson_get_data(element->ptr), element->len);
+						j_message_append_n(message, bson_get_data(element->ptr), element->len); // Writes stream of given length.
 						element->bson_initialized = FALSE;
 					}
 					break;
@@ -281,7 +282,7 @@ j_backend_operation_from_message(JMessage* message, JBackendOperationParam* data
 
 	for (i = 0; i < arrlen; i++)
 	{
-		len = j_message_get_4(message);
+		len = j_message_get_4(message); // Extract the size of the bytes that the first element carries in this message.
 		element = &data[i];
 		element->len = len;
 		if (len)

lib/core/jmessage.c

@@ -259,7 +259,7 @@ j_message_extend(JMessage* message, gsize length)
 
 	if (current_length + length <= message->size)
 	{
-		return;
+		return; // #CHANGE# Some return code should be used here otherwise the caller would presume the method has successfully reallocated the memory.
 	}
 
 	count = j_message_get_count(message);
@@ -272,8 +272,8 @@ j_message_extend(JMessage* message, gsize length)
 	message->size += length * factor;
 
 	position = message->current - message->data;
-	message->data = g_realloc(message->data, message->size);
-	message->current = message->data + position;
+	message->data = g_realloc(message->data, message->size); // Re-allocate the memory.
+	message->current = message->data + position; // Set the position from where the new message section has to be written.
 }
 
 static void

lib/db/jdb-entry.c

@@ -93,7 +93,7 @@ j_db_entry_unref(JDBEntry* entry)
 	if (g_atomic_int_dec_and_test(&entry->ref_count))
 	{
 		j_db_schema_unref(entry->schema);
-		j_bson_destroy(&entry->bson);
+		j_bson_destroy(&entry->bson); // Potential bug. #CHANGE# 'bson' is instantiated before incrementing ref_count.
 		j_bson_destroy(&entry->id);
 		g_free(entry);
 	}
@@ -112,18 +112,21 @@ j_db_entry_set_field(JDBEntry* entry, gchar const* name, gconstpointer value, gu
 	g_return_val_if_fail(name != NULL, FALSE);
 	g_return_val_if_fail(error == NULL || *error == NULL, FALSE);
 
+	// Extract type of the field.
 	if (G_UNLIKELY(!j_db_schema_get_field(entry->schema, name, &type, error)))
 	{
 		goto _error;
 	}
 
+	// Check if field already exists in the entry.
 	if (G_UNLIKELY(!j_bson_has_field(&entry->bson, name, &ret, error)))
 	{
 		goto _error;
 	}
 
 	if (G_UNLIKELY(ret))
 	{
+		// Return as field already exists.
 		g_set_error_literal(error, J_DB_ERROR, J_DB_ERROR_VARIABLE_ALREADY_SET, "variable value must not be set more than once");
 		goto _error;
 	}
@@ -160,6 +163,7 @@ j_db_entry_set_field(JDBEntry* entry, gchar const* name, gconstpointer value, gu
 			g_assert_not_reached();
 	}
 
+	// Append field details to the BSON entry document.
 	if (G_UNLIKELY(!j_bson_append_value(&entry->bson, name, type, &val, error)))
 	{
 		goto _error;
@@ -180,6 +184,7 @@ j_db_entry_insert(JDBEntry* entry, JBatch* batch, GError** error)
 	g_return_val_if_fail(batch != NULL, FALSE);
 	g_return_val_if_fail(error == NULL || *error == NULL, FALSE);
 
+	// Prepare and execute the Entry request at backend.
 	if (G_UNLIKELY(!j_db_internal_insert(entry, batch, error)))
 	{
 		goto _error;
@@ -212,6 +217,7 @@ j_db_entry_update(JDBEntry* entry, JDBSelector* selector, JBatch* batch, GError*
 		goto _error;
 	}
 
+	// Prepare and execute the Entry request at backend.
 	if (G_UNLIKELY(!j_db_internal_update(entry, selector, batch, error)))
 	{
 		goto _error;
@@ -233,6 +239,7 @@ j_db_entry_delete(JDBEntry* entry, JDBSelector* selector, JBatch* batch, GError*
 	g_return_val_if_fail((selector == NULL) || (selector->schema == entry->schema), FALSE);
 	g_return_val_if_fail(error == NULL || *error == NULL, FALSE);
 
+	// Prepare and execute the Entry request at backend.
 	if (G_UNLIKELY(!j_db_internal_delete(entry, selector, batch, error)))
 	{
 		goto _error;