From 3a392d4a9f52923ed4cb359702d80d822ad83a49 Mon Sep 17 00:00:00 2001
From: Cory McWilliams <cory@unprompted.com>
Date: Tue, 5 Mar 2024 12:47:58 -0500
Subject: [PATCH] More .h docs.

---
 src/httpd.js.h |  6 ++++
 src/log.h      |  5 +++
 src/mem.h      | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 106 insertions(+)

diff --git a/src/httpd.js.h b/src/httpd.js.h
index 1b165672..f9d1d51d 100644
--- a/src/httpd.js.h
+++ b/src/httpd.js.h
@@ -13,6 +13,12 @@
 
 #include "quickjs.h"
 
+/**
+** Register the HTTP script interface.  Also registers a number of built-in
+** request handlers.  An ongoing project is to move the JS request handlers
+** into C, after which point this will only do the latter.
+** @param context The JS context.
+*/
 void tf_httpd_register(JSContext* context);
 
 /** @} */
diff --git a/src/log.h b/src/log.h
index 452a37df..cfbe7261 100644
--- a/src/log.h
+++ b/src/log.h
@@ -5,6 +5,11 @@
 ** @{
 */
 
+/**
+** Log a message using printf-style formatting.  Tries to use appropriate
+** platform-specific functionality where necessary to make sure output goes
+** somewhere that it can be seen.
+*/
 #if defined(__ANDROID__)
 #include <android/log.h>
 #define tf_printf(...) __android_log_print(ANDROID_LOG_INFO, "tildefriends", __VA_ARGS__)
diff --git a/src/mem.h b/src/mem.h
index 57044a60..120b01ac 100644
--- a/src/mem.h
+++ b/src/mem.h
@@ -12,43 +12,138 @@
 #include <stddef.h>
 #include <stdint.h>
 
+/** JS malloc functions. */
 typedef struct JSMallocFunctions JSMallocFunctions;
 
+/**
+** Do early setup for memory tracking.
+** @param tracking Whether tracking will be enabled, which adds a time and
+** memory cost of storing stack traces for every allocation.
+*/
 void tf_mem_startup(bool tracking);
+
+/**
+** Clean up the memory system.
+*/
 void tf_mem_shutdown();
 
+/**
+** Register a custom allocator with libuv.
+*/
 void tf_mem_replace_uv_allocator();
+
+/**
+** Get the number of bytes currently allocated by libuv.
+** @return The allocated size in bytes.
+*/
 size_t tf_mem_get_uv_malloc_size();
 
+/**
+** Register a custom allocator with OpenSSL.
+*/
 void tf_mem_replace_tls_allocator();
+
+/**
+** Get the number of bytes currently allocated by OpenSSL.
+** @return The allocated size in bytes.
+*/
 size_t tf_mem_get_tls_malloc_size();
 
+/**
+** Register a custom allocator with SQLite.
+*/
 void tf_mem_replace_sqlite_allocator();
+
+/**
+** Get the number of bytes currently allocated by SQLite.
+** @return The allocated size in bytes.
+*/
 size_t tf_mem_get_sqlite_malloc_size();
 
+/**
+** Get the number of bytes currently allocated by tf_malloc().
+** @return The allocated size in bytes.
+*/
 size_t tf_mem_get_tf_malloc_size();
 
+/**
+** Allocate memory.  Like malloc() but with more tracking.
+** @param size The number of bytes to allocate.
+** @return The allocated memory.
+*/
 void* tf_malloc(size_t size);
+
+/**
+** Reallocate memory.  Like realloc() but with more tracking.
+** @param ptr The previously allocated memory or NULL.
+** @param size The new desired size.
+** @return The new allocation.
+*/
 void* tf_realloc(void* ptr, size_t size);
+
+/**
+** Free memory allocated by tf_malloc() or tf_realloc().
+** @param ptr The allocation.
+*/
 void tf_free(void* ptr);
+
+/**
+** Duplicate a string.
+** @param string The string to copy.
+** @return The newly allocated string.  Free with tf_free().
+*/
 char* tf_strdup(const char* string);
 
+/**
+** Resize a vector.  Like tf_realloc() but overallocatess and prefers not to
+** shrink in order to speed up repeated growth.
+** @param ptr The allocation to resize.
+** @param size The desired new size.
+** @return The new allocation.
+*/
 void* tf_resize_vec(void* ptr, size_t size);
 
+/**
+** Populate a struct with custom JS allocation functions.
+** @param[out] out The struct to receive the functions.
+*/
 void tf_get_js_malloc_functions(JSMallocFunctions* out);
+
+/**
+** Get the number of bytes currently allocated by JS allocators.
+** @return The allocated size in bytes.
+*/
 size_t tf_mem_get_js_malloc_size();
 
+/**
+** Call a function for every live memory allocation.
+** @param callback The callback to call.
+** @param user_data User data to pass to the callback.
+*/
 void tf_mem_walk_allocations(void (*callback)(void* ptr, size_t size, int frames_count, void* const* frames, void* user_data), void* user_data);
 
+/**
+** Information about a memory allocation.
+*/
 typedef struct _tf_mem_allocation_t
 {
+	/** A hash of the callstack used for determining uniqueness. */
 	uint32_t stack_hash;
+	/** The number of instances of this allocation. */
 	int count;
+	/** The size of this allocation. */
 	size_t size;
+	/** The callstack from which this allocation was made. */
 	void* frames[32];
+	/** The number of frames in the callstack. */
 	int frames_count;
 } tf_mem_allocation_t;
 
+/**
+** Generate a list of live allocations.
+** @param[out] out_count The number of allocations returned.
+** @return An array of allocation information.  Free with tf_free().
+*/
 tf_mem_allocation_t* tf_mem_summarize_allocations(int* out_count);
 
 /** @} */