11 make docs warnings left, but I'm out of time for tonight.

src/ssb.db.h

@@ -114,47 +114,213 @@ bool tf_ssb_db_blob_store(tf_ssb_t* ssb, const uint8_t* blob, size_t size, char*
 ** @return The message.
 */
 JSValue tf_ssb_db_get_message_by_id(tf_ssb_t* ssb, const char* id, bool is_keys);
+
+/**
+** Get a message by its author and sequence number.
+** @param ssb The SSB instance.
+** @param author The author's identity.
+** @param sequence The message sequence number.
+** @param[out] out_message_id Populated with the message identifier.
+** @param out_message_id_size The size of the out_message_id buffer.
+** @param[out] out_timestamp Populated with the timestamp.
+** @param[out] out_content Populated with the message content.  Free with tf_free().
+** @return True if the message was found and retrieved.
+*/
 bool tf_ssb_db_get_message_by_author_and_sequence(
 	tf_ssb_t* ssb, const char* author, int64_t sequence, char* out_message_id, size_t out_message_id_size, double* out_timestamp, char** out_content);
+
+/**
+** Get information about the last message from an author.
+** @param ssb The SSB instance.
+** @param author The author's identity.
+** @param[out] out_sequence Populated with the message sequence number.
+** @param[out] out_message_id Populated with the message identifier.
+** @param out_message_id_size The size of the out_message_id buffer.
+** @return True if the message was found and information was retrieved.
+*/
 bool tf_ssb_db_get_latest_message_by_author(tf_ssb_t* ssb, const char* author, int64_t* out_sequence, char* out_message_id, size_t out_message_id_size);
+
+/**
+** Call a function for each result row of an SQL query.
+** @param ssb The SSB instance.
+** @param query The SQL query.
+** @param binds An array of values to bind to SQL parameters.
+** @param callback A callback to call for each result row.
+** @param user_data User data to pass to the callback.
+** @return A promise resolved when the query completes or rejected if it fails.
+*/
 JSValue tf_ssb_db_visit_query(tf_ssb_t* ssb, const char* query, const JSValue binds, void (*callback)(JSValue row, void* user_data), void* user_data);
 
+/**
+** Sanity check the feed for the given author.
+** @param db The SQLite database instance to use.
+** @param author The identity of the author to check.
+** @return True if the author's feed is fully valid.
+*/
 bool tf_ssb_db_check(sqlite3* db, const char* author);
 
+/**
+** Get the number of SSB identities a Tilde Friends user has.
+** @param ssb The SSB instance.
+** @param user The user's username.
+** @return The number of identities found.
+*/
 int tf_ssb_db_identity_get_count_for_user(tf_ssb_t* ssb, const char* user);
+
+/**
+** Create a new identity for a user.
+** @param ssb The SSB instance.
+** @param user The user's username.
+** @param[out] out_public_key A buffer populated with the new public key.
+** @param[out] out_private_key A buffer populated with the new privatee key.
+** @return True if the identity was created.
+*/
 bool tf_ssb_db_identity_create(tf_ssb_t* ssb, const char* user, uint8_t* out_public_key, uint8_t* out_private_key);
+
+/**
+** Delete an identity for a user from the database.  This is an unrecoverable operation.
+** @param ssb The SSB instance.
+** @param user The user's username.
+** @param public_key The identity to delete.
+** @return True if the identity was deleted.
+*/
 bool tf_ssb_db_identity_delete(tf_ssb_t* ssb, const char* user, const char* public_key);
+
+/**
+** Add an identity for a user to the database.
+** @param ssb The SSB instance.
+** @param user The user's username.
+** @param public_key The public key of the identity.
+** @param private_key The private key of the identity.
+*/
 bool tf_ssb_db_identity_add(tf_ssb_t* ssb, const char* user, const char* public_key, const char* private_key);
+
+/**
+** Call a function for each identity owned by a user.
+** @param ssb The SSB instance.
+** @param user The user's username.
+** @param callback The function to call for each identity.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_db_identity_visit(tf_ssb_t* ssb, const char* user, void (*callback)(const char* identity, void* user_data), void* user_data);
+
+/**
+** Call a function for all identities in the database.
+** @param ssb The SSB instance.
+** @param callback The callback to call for each identity.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_db_identity_visit_all(tf_ssb_t* ssb, void (*callback)(const char* identity, void* user_data), void* user_data);
+
+/**
+** Get the private key for an identity in the database.
+** @param ssb The SSB instance.
+** @param user The owning user's username.
+** @param public_key The public key of the identity.
+** @param[out] out_private_key A buffer to receive the private key of the identity.
+** @param private_key_size The size of the out_private_key buffer.
+** @return True if the private key was found and retrieved.
+*/
 bool tf_ssb_db_identity_get_private_key(tf_ssb_t* ssb, const char* user, const char* public_key, uint8_t* out_private_key, size_t private_key_size);
 
+/**
+** Format a message in the standard format for SSB signing.
+** @param context A JS context.
+** @param previous The previous message identifier.
+** @param author The author's public key.
+** @param sequence The message sequence number.
+** @param timestamp The message timestamp.
+** @param hash The hash type (probably "sha256").
+** @param content The message content.
+** @param signature The signature of the message.
+** @param sequence_before_author The order of the message fields (prefer false).
+*/
 JSValue tf_ssb_format_message(JSContext* context, const char* previous, const char* author, int64_t sequence, double timestamp, const char* hash, const char* content,
 	const char* signature, bool sequence_before_author);
 
+/** Information about a single followed account. */
 typedef struct _tf_ssb_following_t
 {
+	/** The number of known users the account is following. */
 	int following_count;
+	/** The number of known users the account is blocking. */
 	int blocking_count;
+	/** The number of known users following the account. */
 	int followed_by_count;
+	/** The number of known users blocking the account. */
 	int blocked_by_count;
+	/** The account's identity. */
 	char id[k_id_base64_len];
 } tf_ssb_following_t;
 
+/**
+** Get all the identities visible from a set of identities given known follows and blocks.
+** @param ssb The SSB instance.
+** @param ids An array of identities.
+** @param count The number of identities.
+** @param depth The following depth to use (prefer 2).
+** @return An array of identities.  Free with tf_free().
+*/
 const char** tf_ssb_db_following_deep_ids(tf_ssb_t* ssb, const char** ids, int count, int depth);
+
+/**
+** Return information about identities visible from a set of identities given known follows and blocks.
+** @param ssb The SSB instance.
+** @param ids An array of identities.
+** @param count The number of identities.
+** @param depth The following depth to use (prefer 2).
+** @return An array of information about visible accounts.  Fere with tf_free().
+*/
 tf_ssb_following_t* tf_ssb_db_following_deep(tf_ssb_t* ssb, const char** ids, int count, int depth);
+
+/**
+** Get all visible identities from all local accounts.
+** @param ssb The SSB instance.
+** @param depth The following depth to consider (prefer 2).
+** @return The visible identities.  Free with tf_free().
+*/
 const char** tf_ssb_db_get_all_visible_identities(tf_ssb_t* ssb, int depth);
 
+/**
+** Information about a stored SHS connection.
+*/
 typedef struct _tf_ssb_db_stored_connection_t
 {
+	/** The connection's address. */
 	char address[256];
+	/** The network port number of the connection. */
 	int port;
+	/** The identity. */
 	char pubkey[k_id_base64_len];
 } tf_ssb_db_stored_connection_t;
 
+/**
+** Get the list of stored connections from the SSB connection tracker.
+** @param ssb The SSB instance.
+** @param[out] out_count Populated with the number of returned connections.
+** @return Information about all the stored connections.
+*/
 tf_ssb_db_stored_connection_t* tf_ssb_db_get_stored_connections(tf_ssb_t* ssb, int* out_count);
+
+/**
+** Remove a stored connection.
+** @param ssb The SSB instance.
+** @param address The connection address.
+** @param port The connection network port number.
+** @param pubkey The identity of the connection.
+*/
 void tf_ssb_db_forget_stored_connection(tf_ssb_t* ssb, const char* address, int port, const char* pubkey);
 
+/**
+** An SQLite authorizer callback.  See https://www.sqlite.org/c3ref/set_authorizer.html for use.
+** @param user_data User data registered with the authorizer.
+** @param action_code The type of action.
+** @param arg0 Depends on the action.
+** @param arg1 Depends on the action.
+** @param arg2 Depends on the action.
+** @param arg3 Depends on the action.
+** @return A value indicating whether the operation is allowed.
+*/
 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.h

@@ -514,37 +514,221 @@ void tf_ssb_add_connections_changed_callback(tf_ssb_t* ssb, tf_ssb_connections_c
 */
 void tf_ssb_remove_connections_changed_callback(tf_ssb_t* ssb, tf_ssb_connections_changed_callback_t* callback, void* user_data);
 
+/**
+** A callback called when a new broadcast is received or one expires.
+** @param ssb The SSB instance.
+** @param user_data The user data.
+*/
 typedef void(tf_ssb_broadcasts_changed_callback_t)(tf_ssb_t* ssb, void* user_data);
+
+/**
+** Register a callback when broadcasts change.
+** @param ssb The SSB instance.
+** @param callback The callback function.
+** @param cleanup A function to call when the callback is removed.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_add_broadcasts_changed_callback(tf_ssb_t* ssb, tf_ssb_broadcasts_changed_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
+
+/**
+** Remove a callback registered for when broadcasts changed.
+** @param ssb The SSB instance.
+** @param callback The callback function.
+** @param user_data The user data registered with the callback.
+*/
 void tf_ssb_remove_broadcasts_changed_callback(tf_ssb_t* ssb, tf_ssb_broadcasts_changed_callback_t* callback, void* user_data);
 
+/**
+** A callback called when a message is added to the database.
+** @param ssb The SSB instance.
+** @param id The message identifier.
+** @param user_data The user data.
+*/
 typedef void(tf_ssb_message_added_callback_t)(tf_ssb_t* ssb, const char* id, void* user_data);
+
+/**
+** Register a callback called when a message is added to the database.
+** @param ssb The SSB instance.
+** @param callback The callback function.
+** @param cleanup A function to call when the callback is removed.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_add_message_added_callback(tf_ssb_t* ssb, tf_ssb_message_added_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
+
+/**
+** Remove a callback registered for when a message is added to the database.
+** @param ssb The SSB instance.
+** @param callback The callback function.
+** @param user_data User data registered with the callback.
+*/
 void tf_ssb_remove_message_added_callback(tf_ssb_t* ssb, tf_ssb_message_added_callback_t* callback, void* user_data);
+
+/**
+** Call all callbacks registered for when a message is added to the database.
+** @param ssb The SSB instance.
+** @param id The message identity added.
+** @param message_with_keys The message added in the format required if keys are requested.
+*/
 void tf_ssb_notify_message_added(tf_ssb_t* ssb, const char* id, JSValue message_with_keys);
+
+/**
+** Record that a new blob was stored.
+** @param ssb The SSB instance.
+** @param id The identity of the newly stored blob.
+*/
 void tf_ssb_notify_blob_stored(tf_ssb_t* ssb, const char* id);
 
+/**
+** A callback called when a blob is newly requested.
+** @param ssb The SSB instance.
+** @param id The blob identity.
+** @param user_data The user data.
+*/
 typedef void(tf_ssb_blob_want_added_callback_t)(tf_ssb_t* ssb, const char* id, void* user_data);
+
+/**
+** Register a function to be called when a blob is newly requested.
+** @param ssb The SSB instance.
+** @param callback The callback.
+** @param cleanup A function to call when the callback is removed.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_add_blob_want_added_callback(tf_ssb_t* ssb, tf_ssb_blob_want_added_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
+
+/**
+** Remove a callback registered for when a blob is newly requested.
+** @param ssb The SSB instance.
+** @param callback The callback to remove.
+** @param user_data The user data registered with the callback.
+*/
 void tf_ssb_remove_blob_want_added_callback(tf_ssb_t* ssb, tf_ssb_blob_want_added_callback_t* callback, void* user_data);
+
+/**
+** Call all callbacks registered for when a blob is newly requested.
+** @param ssb The SSB instance.
+** @param id The requested blob identity.
+*/
 void tf_ssb_notify_blob_want_added(tf_ssb_t* ssb, const char* id);
 
+/**
+** A function called when a MUXRPC request is made.
+** @param connection The SSB connection.
+** @param flags The RPC flags.
+** @param request_number The request number.
+** @param args Request arguments.
+** @param message The raw message data.
+** @param size The size of the raw message data.
+** @param user_data User data registered with the callback.
+*/
 typedef void(tf_ssb_rpc_callback_t)(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, JSValue args, const uint8_t* message, size_t size, void* user_data);
+
+/**
+** Register a MUXRPC callback by name.
+** @param ssb The SSB instance.
+** @param name The NULL-terminated name.
+** @param callback The callback.
+** @param cleanup A function to be called when the callback is removed.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_add_rpc_callback(tf_ssb_t* ssb, const char** name, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
+
+/**
+** Remove a MUXRPC callback.
+** @param ssb The SSB instance.
+** @param name The NULL-terminated name.
+** @param callback The callback to remove.
+** @param user_data The user data registered with the callback.
+*/
 void tf_ssb_remove_rpc_callback(tf_ssb_t* ssb, const char** name, tf_ssb_rpc_callback_t* callback, void* user_data);
 
+/**
+** Send a MUXRPC message.
+** @param connection The connection on which to send the message.
+** @param flags The message flags.
+** @param request_number The request number.
+** @param message The message payload.
+** @param size The size of the message.
+** @param callback A callback to call if a response is received.
+** @param cleanup A callback to call if the callback is removed.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_connection_rpc_send(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const uint8_t* message, size_t size, tf_ssb_rpc_callback_t* callback,
 	tf_ssb_callback_cleanup_t* cleanup, void* user_data);
+
+/**
+** Send a JSON MUXRPC message.
+** @param connection The connection on which to send the message.
+** @param flags The message flags.
+** @param request_number The request number.
+** @param message The JS message payload.
+** @param callback A callback to call if a response is received.
+** @param cleanup A callback to call if the callback is removed.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_connection_rpc_send_json(
 	tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, JSValue message, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data);
+
+/**
+** Send a MUXRPC error message.
+** @param connection The connection on which to send the message.
+** @param flags The message flags.
+** @param request_number The request number.
+** @param error The error string.
+*/
 void tf_ssb_connection_rpc_send_error(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const char* error);
+
+/**
+** Send a MUXRPC "method not allowed" error message.
+** @param connection The connection on which to send the message.
+** @param flags The message flags.
+** @param request_number The request number.
+** @param name The name of the not-allowed method.
+*/
 void tf_ssb_connection_rpc_send_error_method_not_allowed(tf_ssb_connection_t* connection, uint8_t flags, int32_t request_number, const char* name);
+
+/**
+** Register a callback to be called when a message is received for the given
+** request number.
+** @param connection The connection on which to register the callback.
+** @param request_number The request number.
+** @param callback The callback.
+** @param cleanup The function to call when the callback is removed.
+** @param user_data User data to pass to the callback.
+** @param dependent_connection A connection, which, if removed, invalidates this request.
+*/
 void tf_ssb_connection_add_request(tf_ssb_connection_t* connection, int32_t request_number, tf_ssb_rpc_callback_t* callback, tf_ssb_callback_cleanup_t* cleanup, void* user_data,
 	tf_ssb_connection_t* dependent_connection);
+
+/**
+** Remove a callback registered to be called when a message is received for the
+** given request number.
+** @param connection The connection.
+** @param request_number The request number.
+*/
 void tf_ssb_connection_remove_request(tf_ssb_connection_t* connection, int32_t request_number);
 
+/**
+** A function scheduled to be run later.
+** @param connection The owning connection.
+** @param user_data User data registered with the callback.
+*/
 typedef void(tf_ssb_scheduled_callback_t)(tf_ssb_connection_t* connection, void* user_data);
+
+/**
+** Schedule work to be run when the server is next idle.
+** @param connection The owning connection.
+** @param callback The callback to call.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_connection_schedule_idle(tf_ssb_connection_t* connection, tf_ssb_scheduled_callback_t* callback, void* user_data);
+
+/**
+** Schedule work to run on a worker thread.
+** @param connection The owning connection.
+** @param work_callback The callback to run on a thread.
+** @param after_work_callback The callback to run on the main thread when the work is complete.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_connection_run_work(tf_ssb_connection_t* connection, void (*work_callback)(tf_ssb_connection_t* connection, void* user_data),
 	void (*after_work_callback)(tf_ssb_connection_t* connection, int result, void* user_data), void* user_data);
 
@@ -562,36 +746,150 @@ tf_ssb_connection_t* tf_ssb_connection_tunnel_create(tf_ssb_t* ssb, const char*
 
 int32_t tf_ssb_connection_get_ebt_request_number(tf_ssb_connection_t* connection);
 void tf_ssb_connection_set_ebt_request_number(tf_ssb_connection_t* connection, int32_t request_number);
+
+/**
+** Get the EBT clock for a connection.
+** @param connection An SHS connection.
+** @return The EBT clock.
+*/
 JSValue tf_ssb_connection_get_ebt_send_clock(tf_ssb_connection_t* connection);
+
+/**
+** Set the EBT clock for a connection.
+** @param connection An SHS connection.
+** @param send_clock The clock state.
+*/
 void tf_ssb_connection_set_ebt_send_clock(tf_ssb_connection_t* connection, JSValue send_clock);
+
+/**
+** Get whether the EBT clock has been sent for a connection.
+** @param connection An SHS connection.
+** @return True if the clock has been sent.
+*/
 bool tf_ssb_connection_get_sent_clock(tf_ssb_connection_t* connection);
+
+/**
+** Set the EBT clock sent state for a connection.
+** @param connection An SHS connection.
+** @param sent_clock Whether the clock has been sent.
+*/
 void tf_ssb_connection_set_sent_clock(tf_ssb_connection_t* connection, bool sent_clock);
 
+/**
+** Get the JS class ID of the SSB connection class.
+** @return The class ID
+*/
 JSClassID tf_ssb_get_connection_class_id();
 
+/**
+** Get general statistics about an SSB instance.
+** @param ssb The SSB instance.
+** @param[out] out_stats Populated with performance statistics.
+*/
 void tf_ssb_get_stats(tf_ssb_t* ssb, tf_ssb_stats_t* out_stats);
 
+/**
+** Get information about requested blobs.
+** @param connection An SHS connection.
+** @return Blob wants information.
+*/
 tf_ssb_blob_wants_t* tf_ssb_connection_get_blob_wants_state(tf_ssb_connection_t* connection);
 
+/**
+** Get a report of information about recent disconnections.
+** @param ssb The SSB instance.
+** @param context A JS context.
+** @return Information about disconnections.
+*/
 JSValue tf_ssb_get_disconnection_debug(tf_ssb_t* ssb, JSContext* context);
 
+/**
+** Record whether the calling thread is busy.
+** @param ssb The SSB instance.
+** @param busy True if the calling thread is now busy.
+*/
 void tf_ssb_record_thread_busy(tf_ssb_t* ssb, bool busy);
+
+/**
+** Get an estimate of utilization of all running threads.
+** @param ssb The SSB instance.
+** @return The utilization percent.
+*/
 float tf_ssb_get_average_thread_percent(tf_ssb_t* ssb);
 
+/**
+** Register a callback to be called when the main thread blocks for an
+** unreasonable amount of time.
+** @param ssb The SSB instance.
+** @param callback The callback to call.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_set_hitch_callback(tf_ssb_t* ssb, void (*callback)(const char* name, uint64_t duration_ns, void* user_data), void* user_data);
 
+/**
+** Get the queue of messages in the progress of being stored.
+** @param ssb The SSB instance.
+** @return The queue.
+*/
 tf_ssb_store_queue_t* tf_ssb_get_store_queue(tf_ssb_t* ssb);
 
+/**
+** Increment the SSB instance's ref count.  Prevents it from being destroyed
+** until it reaches zero.
+** @param ssb The SSB instance.
+*/
 void tf_ssb_ref(tf_ssb_t* ssb);
+
+/**
+** Decrement the SSB instance's ref count.  May destroy the instance when the
+** count returns to zero.
+** @param ssb The SSB instance.
+*/
 void tf_ssb_unref(tf_ssb_t* ssb);
 
+/**
+** Record whether the calling thread is the main thread or not.  Some
+** operations are disallowed on the main thread for performance.
+** @param ssb The SSB instance.
+** @param main_thread Whether the calling thread is the main thread.
+*/
 void tf_ssb_set_main_thread(tf_ssb_t* ssb, bool main_thread);
 
+/**
+** Get whether the running server is operating a room.
+** @param ssb The SSB instance.
+** @return True if the server is a room.
+*/
 bool tf_ssb_is_room(tf_ssb_t* ssb);
+
+/**
+** Set whether the running server is operating a room.
+** @param ssb The SSB instance.
+** @param is_room Whether to run a room.
+*/
 void tf_ssb_set_is_room(tf_ssb_t* ssb, bool is_room);
+
+/**
+** Get the name of the room hosted by the running server.
+** @param ssb The SSB instance.
+** @return The room name or NULL.
+*/
 const char* tf_ssb_get_room_name(tf_ssb_t* ssb);
+
+/**
+** Set the name of the room hosted by the running server.
+** @param ssb The SSB instance.
+** @param room_name The name of the room.
+*/
 void tf_ssb_set_room_name(tf_ssb_t* ssb, const char* room_name);
 
+/**
+** Schedule work to be run after a time delay.
+** @param ssb The SSB instance.
+** @param delay_ms The duration to wait in milliseconds.
+** @param callback The callback to call to run the work.
+** @param user_data User data to pass to the callback.
+*/
 void tf_ssb_schedule_work(tf_ssb_t* ssb, int delay_ms, void (*callback)(tf_ssb_t* ssb, void* user_data), void* user_data);
 
 /** @} */