libipc.h now explains basically all the API.

libipc.h

@@ -3,6 +3,47 @@
 
 #include <stdint.h>
 
+/**
+  The LibIPC API is designed to be simple.
+
+  For most applications, the usage can be summarized as:
+
+  - ipc_context_init                         to allocate the "context" structure;
+  - ipc_service_init or ipc_connect_service  to instanciate the service or starts a connection to it;
+  - loop over ipc_wait_event                 to wait for events;
+  - ipc_schedule                             to send messages;
+  - ipc_close_all then ipc_context_deinit    to close all connections then free the context.
+
+  The ipc_wait_event function is where the magic happens.
+  This function handles all the complexity of network management, juggling with file descriptors,
+  storing connection-related data, waiting for an event, handling connections and disconnections,
+  reading incoming messages and providing UNDERSTANDABLE notifications (see the `event_types` enumeration).
+
+  Basic events are:
+
+  - Connections and disconnections, they are already handled within LibIPC, but the API notifies the
+    user so they can perform additional operations;
+  - Messages (received or sent);
+  - Timers, to wake up the application on a regular basis (setup with ipc_context_timer).
+
+  Furthermore, the API can be used for non-IPC communications, meaning connections not using the LibIPC protocol.
+  This is particularly useful when dealing with any file descriptor that needs attention.
+  The ipc_add_external function adds a file descriptor marked as "external" which will be listened on by LibIPC.
+  In this case, disconnections are still handled, but messages aren't automatically read.
+  This way, almost any protocol can be used along with LibIPC communications and with the LibIPC API.
+  Related event: EXTERNAL, notifying users that an "external" file descriptor received a message.
+
+  Finally, a "switch" mechanism to automatically transfer messages between a pair of file descriptors (ipc_add_switch).
+  Messages are automatically exchanged between the two file descriptors by LibIPC;
+  eventually with user-provided callbacks (ipc_set_switch_callbacks) for non-IPC connections.
+  Thus, callbacks enable to handle websocket connections, non-IPC clients communicating with JSON messages, etc.
+  Related events: SWITCH RX and TX, notifying users that a "switched" file descriptor received (or sent) a message.
+
+  Switch and IO callbacks enable to easily create "protocol IPC services" (such as TCPd) to
+  bind IPC services to basically any available protocol through small, dedicated services
+  handling all the nitty-gritty details of non-IPC protocols.
+ */
+
 // Event types: the "t" parameter in "ipc_wait_event".
 enum event_types {
 	  ERROR         = 0  // A problem occured.
@@ -11,8 +52,8 @@ enum event_types {
 	, MESSAGE_RX    = 3  // New message.
 	, MESSAGE_TX    = 4  // Message sent.
 	, TIMER         = 5  // Timeout in the poll(2) function.
-	, EXTERNAL      = 6  // Message received from a non IPC socket.
-	, SWITCH_RX     = 7  // Message received from a switched FD.
+	, EXTERNAL      = 6  // Message received from a non-IPC socket.
+	, SWITCH_RX     = 7  // Message received from a switched fd.
 	, SWITCH_TX     = 8  // Message sent to a switched fd.
 };
 
@@ -59,21 +100,6 @@ int ipc_close_all (void* ctx);
 // which enables to handle any communications for most protocols through the LibIPC API.
 int ipc_add_external (void* ctx, int newfd);
 
-/**
- * SWITCH: enables the automatic exchange of messages between a pair of file descriptors.
- *
- * There are two operations available:
- * - ipc_add_switch: add a new switch;
- * - ipc_set_switch_callbacks: set callbacks (IO operations) for a file descriptor,
- *   enabling specific processing for a connection.
- *
- * Callbacks enable to handle non-IPC communications, for example a websocket connection,
- * a non-IPC client communicating with JSON messages (or any other format), etc.
- *
- * Switch and IO callbacks enable to easily create "protocol IPC services" (such as TCPd) to
- * bind IPC services to basically any available protocol through small, dedicated services
- * handling all the nitty-gritty details of non-IPC protocols.
- */
 // Add a new switch between a pair of file descriptors, enabling automatic exchange of messages
 // between this pair of fds. Useful for "protocol services", such as TCPd.
 int ipc_add_switch (void* ctx, int fd1, int fd2);