Add a Doxyfile and preliminary module-level docs.

GNUmakefile

@@ -872,3 +872,7 @@ dist-test: dist
 format:
 	@clang-format -i $(wildcard src/*.c src/*.h src/*.m)
 .PHONY: format
+
+docs:
+	@doxygen
+.PHONY: docs

src/bcrypt.js.h

@@ -1,5 +1,14 @@
 #pragma once
 
+/**
+** \defgroup bcrypt_js bCrypt
+** Exposes bcrypt to script, where it is used for hashing and verifying
+** passwords.
+** @{
+*/
+
 typedef struct JSContext JSContext;
 
 void tf_bcrypt_register(JSContext* context);
+
+/** @} */

src/bip39.h

@@ -1,8 +1,17 @@
 #pragma once
 
+/**
+** \defgroup bip39 BIP39
+** Convert between raw bytes and \ref bip39_words.
+** See: https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki.
+** @{
+*/
+
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
 
 bool tf_bip39_bytes_to_words(const uint8_t* bytes, size_t bytes_size, char* out_words, size_t words_size);
 bool tf_bip39_words_to_bytes(const char* words, uint8_t* out_bytes, size_t bytes_size);
+
+/** @} */

src/bip39.words.h

@@ -1,7 +1,15 @@
 #pragma once
 
+/**
+** \defgroup bip39_words BIP39 Word list
+** The word list used by \ref bip39.
+** @{
+*/
+
 enum
 {
 	k_bip39_words_count = 2048
 };
 extern const char* k_bip39_words[k_bip39_words_count];
+
+/** @} */

src/database.js.h

@@ -1,5 +1,13 @@
 #pragma once
 
+/**
+** \defgroup database_js Database Interface
+** Exposes a key-value store interface to script.
+** @{
+*/
+
 typedef struct JSContext JSContext;
 
 void tf_database_register(JSContext* context);
+
+/** @} */

src/file.js.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup file_js File Interface
+** Exposes an operating system file I/O API to script.
+** @{
+*/
+
 #include <uv.h>
 
 typedef struct JSContext JSContext;
@@ -9,3 +15,5 @@ void tf_file_register(JSContext* context);
 
 void tf_file_stat(tf_task_t* task, const char* path, void (*callback)(tf_task_t* task, const char* path, int result, const uv_stat_t* stat, void* user_data), void* user_data);
 void tf_file_read(tf_task_t* task, const char* path, void (*callback)(tf_task_t* task, const char* path, int result, const void* data, void* user_data), void* user_data);
+
+/** @} */

src/http.h

@@ -1,5 +1,16 @@
 #pragma once
 
+/**
+** \defgroup http HTTP Server
+** This is a HTTP server.
+**
+** It can listen on multiple ports.  It supports IPv4
+** and IPv6.  It handles websocket connections.  Requests can be handled
+** immediately or at a later time.  It is very bare bones, and that is a
+** feature.
+** @{
+*/
+
 #include <stdbool.h>
 #include <stddef.h>
 
@@ -35,7 +46,13 @@ typedef struct _tf_http_request_t
 typedef void(tf_http_callback_t)(tf_http_request_t* request);
 typedef void(tf_http_cleanup_t)(void* user_data);
 
+/**
+** Create an HTTP server using the given libuv loop.
+** @param loop A libuv loop to use.
+** @return An HTTP server instance.
+*/
 tf_http_t* tf_http_create(uv_loop_t* loop);
+
 void tf_http_set_trace(tf_http_t* http, tf_trace_t* trace);
 int tf_http_listen(tf_http_t* http, int port, tf_tls_context_t* tls, tf_http_cleanup_t* cleanup, void* user_data);
 void tf_http_add_handler(tf_http_t* http, const char* pattern, tf_http_callback_t* callback, tf_http_cleanup_t* cleanup, void* user_data);
@@ -53,3 +70,5 @@ void tf_http_request_send(tf_http_request_t* request, const void* data, size_t s
 void tf_http_request_websocket_upgrade(tf_http_request_t* request);
 
 const char* tf_http_status_text(int status);
+
+/** @} */

src/httpd.js.h

@@ -1,5 +1,18 @@
 #pragma once
 
+/**
+** \defgroup httpd_js HTTPD Interface
+** Exposes the \ref http server to script and registers a number of built-in
+** endpoints.
+**
+** core/core.js is gradually being moved from JS to C here, at which point this will
+** no longer be a bridge between the two and instead primarily expose the web API.
+**
+** @{
+*/
+
 #include "quickjs.h"
 
 void tf_httpd_register(JSContext* context);
+
+/** @} */

src/index.md

@@ -0,0 +1 @@
+\mainpage Tilde Friends Source Documentation

src/log.h

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+** \defgroup log Logging helpers
+** @{
+*/
+
 #if defined(__ANDROID__)
 #include <android/log.h>
 #define tf_printf(...) __android_log_print(ANDROID_LOG_INFO, "tildefriends", __VA_ARGS__)
@@ -22,3 +27,5 @@
 #include <stdio.h>
 #define tf_printf printf
 #endif
+
+/** @} */

src/mem.h

@@ -1,5 +1,13 @@
 #pragma once
 
+/**
+** \defgroup mem Memory management
+** tf_malloc() and friends use malloc() behind the scenes but optionally
+** track memory per system (OpenSSL, sqlite, libuv, ...) and store callstacks
+** to help debug leaks.
+** @{
+*/
+
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
@@ -42,3 +50,5 @@ typedef struct _tf_mem_allocation_t
 } tf_mem_allocation_t;
 
 tf_mem_allocation_t* tf_mem_summarize_allocations(int* out_count);
+
+/** @} */

src/packetstream.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup packetstream Packet Stream
+** Primitive helper for sending packets of known size across a pipe.
+** @{
+*/
+
 #include <stddef.h>
 
 typedef struct uv_pipe_s uv_pipe_t;
@@ -16,3 +22,5 @@ void tf_packetstream_send(tf_packetstream_t* stream, int packet_type, const char
 void tf_packetstream_set_on_receive(tf_packetstream_t* stream, tf_packetstream_onreceive_t* callback, void* user_data);
 void tf_packetstream_close(tf_packetstream_t* stream);
 uv_pipe_t* tf_packetstream_get_pipe(tf_packetstream_t* stream);
+
+/** @} */

src/serialize.h

@@ -1,5 +1,12 @@
 #pragma once
 
+/**
+** \defgroup serialize JS binary serialization
+** Converts JS data to a basic binary format with support for exporting
+** functions so that they can be called across the barrier, too.
+** @{
+*/
+
 #include "quickjs.h"
 
 typedef struct _tf_task_t tf_task_t;
@@ -7,3 +14,5 @@ typedef struct _tf_taskstub_t tf_taskstub_t;
 
 void tf_serialize_store(tf_task_t* task, tf_taskstub_t* to, void** out_buffer, size_t* out_size, JSValue value);
 JSValue tf_serialize_load(tf_task_t* task, tf_taskstub_t* from, const char* buffer, size_t size);
+
+/** @} */

src/socket.js.h

@@ -1,7 +1,15 @@
 #pragma once
 
+/**
+** \defgroup socket_js Socket Interface
+** Exposes network sockets to script.
+** @{
+*/
+
 #include "quickjs.h"
 
 JSValue tf_socket_register(JSContext* context);
 int tf_socket_get_count();
 int tf_socket_get_open_count();
+
+/** @} */

src/ssb.connections.h

@@ -1,5 +1,12 @@
 #pragma once
 
+/**
+** \defgroup ssb_connections SSB Connections
+** Primitive tracking for SSB connections, as in we tried to connect to host X
+** Y seconds ago, and it failed.  This needs to be replaced with something better.
+** @{
+*/
+
 typedef struct _tf_ssb_t tf_ssb_t;
 typedef struct _tf_ssb_connections_t tf_ssb_connections_t;
 
@@ -9,3 +16,5 @@ void tf_ssb_connections_destroy(tf_ssb_connections_t* connections);
 void tf_ssb_connections_store(tf_ssb_connections_t* connections, const char* host, int port, const char* key);
 void tf_ssb_connections_set_attempted(tf_ssb_connections_t* connections, const char* host, int port, const char* key);
 void tf_ssb_connections_set_succeeded(tf_ssb_connections_t* connections, const char* host, int port, const char* key);
+
+/** @} */

src/ssb.db.h

@@ -1,5 +1,12 @@
 #pragma once
 
+/**
+** \defgroup ssb_db SSB Database
+** This is the main interface to SSB persistence.  Everything about getting and
+** storing messages and blobs goes through here.
+** @{
+*/
+
 #include "ssb.h"
 
 #include "quickjs.h"
@@ -66,3 +73,5 @@ tf_ssb_db_stored_connection_t* tf_ssb_db_get_stored_connections(tf_ssb_t* ssb, i
 void tf_ssb_db_forget_stored_connection(tf_ssb_t* ssb, const char* address, int port, const char* pubkey);
 
 int tf_ssb_sqlite_authorizer(void* user_data, int action_code, const char* arg0, const char* arg1, const char* arg2, const char* arg3);
+
+/** @} */

src/ssb.export.h

@@ -1,5 +1,15 @@
 #pragma once
 
+/**
+** \defgroup tf_export Tilde Friends Export
+** Support for exporting Tilde Friends apps from the database to disk.
+**
+** I don't know why it has SSB in the name.
+** @{
+*/
+
 typedef struct _tf_ssb_t tf_ssb_t;
 
 void tf_ssb_export(tf_ssb_t* ssb, const char* key);
+
+/** @} */

src/ssb.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup ssb SSB
+** Everything about SSB, SHS, and MUXRPC happens here.
+** @{
+*/
+
 #include "quickjs.h"
 
 #include <stdbool.h>
@@ -230,3 +236,5 @@ const char* tf_ssb_get_room_name(tf_ssb_t* ssb);
 void tf_ssb_set_room_name(tf_ssb_t* ssb, const char* room_name);
 
 void tf_ssb_schedule_work(tf_ssb_t* ssb, int delay_ms, void (*callback)(tf_ssb_t* ssb, void* user_data), void* user_data);
+
+/** @} */

src/ssb.import.h

@@ -1,6 +1,16 @@
 #pragma once
 
+/**
+** \defgroup tf_import Tilde Friends Import
+** Support for importing Tilde Friends apps from disk to the database.
+**
+** I don't know why it has SSB in the name.
+** @{
+*/
+
 typedef struct _tf_ssb_t tf_ssb_t;
 
 void tf_ssb_import(tf_ssb_t* ssb, const char* user, const char* path);
 void tf_ssb_import_from_zip(tf_ssb_t* ssb, const char* zip_path, const char* user, const char* path);
+
+/** @} */

src/ssb.js.h

@@ -1,6 +1,14 @@
 #pragma once
 
+/**
+** \defgroup ssb_js SSB Interface
+** Exposes SSB to JS.
+** @{
+*/
+
 typedef struct JSContext JSContext;
 typedef struct _tf_ssb_t tf_ssb_t;
 
 void tf_ssb_register(JSContext* context, tf_ssb_t* ssb);
+
+/** @} */

src/ssb.rpc.h

@@ -1,6 +1,15 @@
 #pragma once
 
+/**
+** \defgroup ssb_rpc SSB RPC
+** Implementations of all the necessary MUXRPC handlers (createHistoryStream,
+** ebt.replicate, blobs.get, ...).
+** @{
+*/
+
 typedef struct _tf_ssb_t tf_ssb_t;
 
 void tf_ssb_rpc_register(tf_ssb_t* ssb);
 void tf_ssb_rpc_start_periodic(tf_ssb_t* ssb);
+
+/** @} */

src/ssb.tests.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup ssb_tests SSB Tests
+** Tests for SSB functionality.
+** @{
+*/
+
 typedef struct _tf_test_options_t tf_test_options_t;
 
 void tf_ssb_test_id_conversion(const tf_test_options_t* options);
@@ -8,3 +14,5 @@ void tf_ssb_test_following(const tf_test_options_t* options);
 void tf_ssb_test_rooms(const tf_test_options_t* options);
 void tf_ssb_test_bench(const tf_test_options_t* options);
 void tf_ssb_test_go_ssb_room(const tf_test_options_t* options);
+
+/** @} */

src/task.h

@@ -1,5 +1,14 @@
 #pragma once
 
+/**
+** \defgroup task Task
+** Task is responsible for running JS in C.  It exposes just what is needed for
+** sandboxed or trusted code, helps with communiciation between parent and
+** child processes, including function calls and async operations across the
+** boundaries.
+** @{
+*/
+
 #include <stdbool.h>
 
 #include "quickjs.h"
@@ -80,3 +89,5 @@ bool tf_task_send_error_to_parent(tf_task_t* task, JSValue error);
 char* tf_task_get_disconnections(tf_task_t* task);
 char* tf_task_get_debug(tf_task_t* task);
 char* tf_task_get_hitches(tf_task_t* task);
+
+/** @} */

src/taskstub.js.h

@@ -1,5 +1,12 @@
 #pragma once
 
+/**
+** \defgroup taskstub Task Stub
+** Task Stub is a poorly-named representation of a remote Task that can be
+** exposed to JS.
+** @{
+*/
+
 #include "quickjs.h"
 #include "uv.h"
 
@@ -18,3 +25,5 @@ tf_task_t* tf_taskstub_get_owner(const tf_taskstub_t* stub);
 tf_taskstub_t* tf_taskstub_create_parent(tf_task_t* task, uv_file file);
 void tf_taskstub_on_error(tf_taskstub_t* stub, JSValue error);
 void tf_taskstub_on_print(tf_taskstub_t* stub, JSValue arguments);
+
+/** @} */

src/tests.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup tests Tests
+** This is the test harness.
+** @{
+*/
+
 typedef struct _tf_test_options_t
 {
 	const char* exe_path;
@@ -7,3 +13,5 @@ typedef struct _tf_test_options_t
 } tf_test_options_t;
 
 void tf_tests(const tf_test_options_t* options);
+
+/** @} */

src/tls.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup tls TLS
+** A minimal wrapper around OpenSSL.
+** @{
+*/
+
 #include <stdbool.h>
 #include <stddef.h>
 
@@ -39,3 +45,5 @@ int tf_tls_session_write_plain(tf_tls_session_t* session, const char* buffer, si
 int tf_tls_session_read_encrypted(tf_tls_session_t* session, char* buffer, size_t bytes);
 int tf_tls_session_write_encrypted(tf_tls_session_t* session, const char* buffer, size_t bytes);
 bool tf_tls_session_get_error(tf_tls_session_t* session, char* buffer, size_t bytes);
+
+/** @} */

src/tlscontext.js.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup tls_js TLS Interface
+** Exposes \ref tls to JS.
+** @{
+*/
+
 #include "quickjs.h"
 
 typedef struct _tf_tls_context_t tf_tls_context_t;
@@ -7,3 +13,5 @@ typedef struct _tf_tls_context_t tf_tls_context_t;
 JSValue tf_tls_context_register(JSContext* context);
 tf_tls_context_t* tf_tls_context_get(JSValue value);
 int tf_tls_context_get_count();
+
+/** @} */

src/trace.h

@@ -1,5 +1,13 @@
 #pragma once
 
+/**
+** \defgroup trace Performance Tracing
+** Generates trace output that is compatible with speedscope.app,
+** chrome://tracing or ui.perfetto.dev for scrutining what each thread is doing
+** for optimization purposes.
+** @{
+*/
+
 #include <inttypes.h>
 #include <stddef.h>
 
@@ -22,3 +30,5 @@ void tf_trace_set_write_callback(tf_trace_t* trace, tf_trace_write_callback_t* c
 void tf_trace_raw(tf_trace_t* trace, const char* buffer, size_t size);
 
 void tf_trace_sqlite(tf_trace_t* trace, sqlite3* sqlite);
+
+/** @} */

src/util.js.h

@@ -1,5 +1,11 @@
 #pragma once
 
+/**
+** \defgroup util_js Utilities
+** This is becoming just a dumping ground of small helpers.
+** @{
+*/
+
 #include "quickjs.h"
 
 #include <stdbool.h>
@@ -28,3 +34,5 @@ const char* tf_util_function_to_string(void* function);
 		__typeof__(b) _b = (b); \
 		_a > _b ? _b : _a; \
 	})
+
+/** @} */