tomsg_clientlib: Document better

1 files changed, 37 insertions, 2 deletions

diff --git a/ssh/tomsg_clientlib.h b/ssh/tomsg_clientlib.h
index f560728..58ad4d4 100644
--- a/ssh/tomsg_clientlib.h
+++ b/ssh/tomsg_clientlib.h
@@ -5,6 +5,14 @@
 #include <stdint.h>
 
 
+// This is a fairly low-level client library for the tomsg protocol. No state
+// is kept; the API just allows for sending commands and receiving responses
+// and push messages from the server.
+// Use tomsg_connect() to connect, then wait for messages by poll(2)'ing on the
+// file descriptor returned by tomsg_poll_fd(). To send a command, use
+// functions like tomsg_register(), tomsg_send(), etc.
+
+
 struct tomsg_client;
 
 enum tomsg_retval {
@@ -22,16 +30,25 @@ enum tomsg_retval {
 	TOMSG_ERR_MEMORY,     // Error allocating memory
 };
 
+// Returns reference to internal static buffer.
 const char* tomsg_strerror(enum tomsg_retval code);
 
+// If successful, stores a new connection structure in 'client' and returns
+// TOMSG_OK. On error, stores NULL in 'client' and returns an error code.
 enum tomsg_retval tomsg_connect(
 	const char *hostname, int port,
 	struct tomsg_client **client  // output
 );
 
-// Will also free the client structure
+// Close the connection. This also frees the client structure. Note that even
+// in case of an error, you must still call this function to prevent a memory
+// leak.
 void tomsg_close(struct tomsg_client *client);
 
+// Returns a file descriptor that can be listened for read-ready events (using
+// e.g. select(2) or poll(2)). Whenever it becomes ready for reading, you
+// should call tomsg_next_event(). If the connection was already closed
+// internally due to an error, returns -1.
 int tomsg_poll_fd(const struct tomsg_client *client);
 
 enum tomsg_event_type {
@@ -116,6 +133,11 @@ struct tomsg_event {
 	};
 };
 
+// Free the fields in the event structure corresponding to the event type set.
+// The structure memory may be re-used for a different event afterwards. Note
+// that, despite the name, the fields are not actually set to NULL -- they
+// couldn't be, since the structure is passed by value (to indicate ownership
+// transfer).
 void tomsg_event_nullify(struct tomsg_event event);
 
 // Will return TOMSG_ERR_AGAIN if no events are available at present. In that
@@ -127,27 +149,35 @@ enum tomsg_retval tomsg_next_event(
 	struct tomsg_event *event  // output
 );
 
+// Send a register command to the server.
 enum tomsg_retval tomsg_register(
 	struct tomsg_client *client,
 	const char *username, const char *password
 );
 
+// Send a login command to the server.
 enum tomsg_retval tomsg_login(
 	struct tomsg_client *client,
 	const char *username, const char *password
 );
 
+// Send a logout command to the server.
 enum tomsg_retval tomsg_logout(struct tomsg_client *client);
 
+// Send a list_rooms command to the server.
 enum tomsg_retval tomsg_list_rooms(struct tomsg_client *client);
 
+// Send a list_members command to the server.
 enum tomsg_retval tomsg_list_members(struct tomsg_client *client, const char *room_name);
 
+// Send a create_room command to the server.
 enum tomsg_retval tomsg_create_room(struct tomsg_client *client);
 
+// Send an invite command to the server.
 enum tomsg_retval tomsg_invite(
 	struct tomsg_client *client, const char *room_name, const char *username);
 
+// Send a send command to the server.
 // If 'tag' is not NULL, will write the message request tag to the referenced
 // location. This tag will also be given in the TOMSG_EV_SEND response, so that
 // the response can be linked to the original message.
@@ -156,13 +186,18 @@ enum tomsg_retval tomsg_send(
 	int64_t *tag  // output
 );
 
-// pass -1 to 'before_msgid' to return the latest 'count'
+// Send a history command to the server.
+// Pass -1 to 'before_msgid' to return the latest 'count' instead messages
+// before that id.
 enum tomsg_retval tomsg_history(
 	struct tomsg_client *client, const char *room_name,
 	int64_t count, int64_t before_msgid);
 
+// Send a ping command to the server.
 enum tomsg_retval tomsg_ping(struct tomsg_client *client);
 
+// Send an is_online command to the server.
 enum tomsg_retval tomsg_is_online(struct tomsg_client *client, const char *username);
 
+// Send a user_active command to the server.
 enum tomsg_retval tomsg_user_active(struct tomsg_client *client, bool active);