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);
 
 /** @} */