BConnection: add documentation

system/BConnection.h

@@ -32,28 +32,100 @@
 
 
 
+/**
+ * Checks if the given address is supported by {@link BConnection} and related objects.
+ * 
+ * @param addr address to check. Must be a proper {@link BAddr} object according to
+ *             {@link BIPAddr_Assert}.
+ * @return 1 if supported, 0 if not
+ */
 int BConnection_AddressSupported (BAddr addr);
 
 
 
 struct BListener_s;
+
+/**
+ * Object which listens for connections on an address.
+ * When a connection is ready, the {@link BListener_handler} handler is called, from which
+ * the connection can be accepted into a new {@link BConnection} object.
+ */
 typedef struct BListener_s BListener;
 
+/**
+ * Handler called when a new connection is ready.
+ * The connection can be accepted by calling {@link BConnection_Init} with the a
+ * BCONNECTION_SOURCE_LISTENER 'source' argument.
+ * If no attempt is made to accept the connection from the job closure of this handler,
+ * the connection will be discarded.
+ * 
+ * @param user as in {@link BListener_Init}
+ */
 typedef void (*BListener_handler) (void *user);
 
+/**
+ * Initializes the object.
+ * {@link BNetwork_GlobalInit} must have been done.
+ * 
+ * @param o the object
+ * @param addr address to listen on. Must be supported according to {@link BConnection_AddressSupported}.
+ * @param reactor reactor we live in
+ * @param user argument to handler
+ * @param handler handler called when a connection can be accepted
+ * @return 1 on success, 0 on failure
+ */
 int BListener_Init (BListener *o, BAddr addr, BReactor *reactor, void *user,
                     BListener_handler handler) WARN_UNUSED;
+
+/**
+ * Frees the object.
+ * 
+ * @param o the object
+ */
 void BListener_Free (BListener *o);
 
 
 
 struct BConnector_s;
+
+/**
+ * Object which connects to an address.
+ * When the connection attempt finishes, the {@link BConnector_handler} handler is called, from which,
+ * if successful, the resulting connection can be moved to a new {@link BConnection} object.
+ */
 typedef struct BConnector_s BConnector;
 
+/**
+ * Handler called when the connection attempt finishes.
+ * If the connection attempt succeeded (is_error==0), the new connection can be used by calling
+ * {@link BConnection_Init} with a BCONNECTION_SOURCE_TYPE_CONNECTOR 'source' argument.
+ * This handler will be called at most once. The connector object need not be freed after it
+ * is called. 
+ * 
+ * @param user as in {@link BConnector_Init}
+ * @param is_error whether the connection attempt succeeded (0) or failed (1)
+ */
 typedef void (*BConnector_handler) (void *user, int is_error);
 
+/**
+ * Initializes the object.
+ * {@link BNetwork_GlobalInit} must have been done.
+ * 
+ * @param o the object
+ * @param addr address to connect to. Must be supported according to {@link BConnection_AddressSupported}.
+ * @param reactor reactor we live in
+ * @param user argument to handler
+ * @param handler handler called when the connection attempt finishes
+ * @return 1 on success, 0 on failure
+ */
 int BConnector_Init (BConnector *o, BAddr addr, BReactor *reactor, void *user,
                      BConnector_handler handler) WARN_UNUSED;
+
+/**
+ * Frees the object.
+ * 
+ * @param o the object
+ */
 void BConnector_Free (BConnector *o);
 
 
@@ -104,25 +176,143 @@ struct BConnection_source {
 
 
 struct BConnection_s;
+
+/**
+ * Object which represents a stream connection. This is usually a TCP connection, either client
+ * or server, but may also be used with any file descriptor (e.g. pipe) on Unix-like systems.
+ * Sending and receiving is performed via {@link StreamPassInterface} and {@link StreamRecvInterface},
+ * respectively.
+ */
 typedef struct BConnection_s BConnection;
 
 #define BCONNECTION_EVENT_ERROR 1
 #define BCONNECTION_EVENT_RECVCLOSED 2
 
+/**
+ * Handler called when an error occurs or the receive end of the connection was closed
+ * by the remote peer.
+ * - If event is BCONNECTION_EVENT_ERROR, the connection is no longer usable and must be freed
+ *   from withing the job closure of this handler. No further I/O or interface initialization
+ *   must occur.
+ * - If event is BCONNECTION_EVENT_RECVCLOSED, no further receive I/O or receive interface
+ *   initialization must occur. It is guarantted that the receive interface was initialized.
+ * 
+ * @param user as in {@link BConnection_Init} or {@link BConnection_SetHandlers}
+ * @param event what happened - BCONNECTION_EVENT_ERROR or BCONNECTION_EVENT_RECVCLOSED
+ */
 typedef void (*BConnection_handler) (void *user, int event);
 
+/**
+ * Initializes the object.
+ * {@link BNetwork_GlobalInit} must have been done.
+ * 
+ * @param o the object
+ * @param source specifies what the connection comes from. This argument must be created with one of the
+ *               following macros:
+ *               - BCONNECTION_SOURCE_LISTENER(BListener *, BAddr *)
+ *                 Accepts a connection ready on a {@link BListener} object. Must be called from the job
+ *                 closure of the listener's {@link BListener_handler}, and must be the first attempt
+ *                 for this handler invocation. The address of the client is written if the address
+ *                 argument is not NULL (theoretically an invalid address may be returned).
+ *               - BCONNECTION_SOURCE_CONNECTOR(Bconnector *)
+ *                 Uses a connection establised with {@link BConnector}. Must be called from the job
+ *                 closure of the connector's {@link BConnector_handler}, the handler must be reporting
+ *                 successful connection, and must be the first attempt for this handler invocation.
+ *               - BCONNECTION_SOURCE_PIPE(int)
+ *                 On Unix-like systems, uses the provided file descriptor. The file descriptor number must
+ *                 be >=0.
+ * @param reactor reactor we live in
+ * @param user argument to handler
+ * @param handler handler called when an error occurs or the receive end of the connection was closed
+ *                by the remote peer.
+ * @return 1 on success, 0 on failure
+ */
 int BConnection_Init (BConnection *o, struct BConnection_source source, BReactor *reactor, void *user,
                       BConnection_handler handler) WARN_UNUSED;
+
+/**
+ * Frees the object.
+ * The send and receive interfaces must not be initialized.
+ * If the connection was created with a BCONNECTION_SOURCE_PIPE 'source' argument, the file descriptor
+ * will not be closed.
+ * 
+ * @param o the object
+ */
 void BConnection_Free (BConnection *o);
+
+/**
+ * Updates the handler function.
+ * 
+ * @param o the object
+ * @param user argument to handler
+ * @param handler new handler function, as in {@link BConnection_Init}. Additionally, may be NULL to
+ *                remove the current handler. In this case, a proper handler must be set before anything
+ *                can happen with the connection. This is used when moving the connection ownership from
+ *                one module to another.
+ */
 void BConnection_SetHandlers (BConnection *o, void *user, BConnection_handler handler);
+
+/**
+ * Sets the SO_SNDBUF socket option.
+ * 
+ * @param o the object
+ * @param buf_size value for SO_SNDBUF option
+ * @return 1 on success, 0 on failure
+ */
 int BConnection_SetSendBuffer (BConnection *o, int buf_size);
 
+/**
+ * Initializes the send interface for the connection.
+ * The send interface must not be initialized.
+ * 
+ * @param o the object
+ */
 void BConnection_SendAsync_Init (BConnection *o);
+
+/**
+ * Frees the send interface for the connection.
+ * The send interface must be initialized.
+ * If the send interface was busy when this is called, the connection is no longer usable and must be
+ * freed before any further I/O or interface initialization.
+ * 
+ * @param o the object
+ */
 void BConnection_SendAsync_Free (BConnection *o);
+
+/**
+ * Returns the send interface.
+ * The send interface must be initialized.
+ * 
+ * @param o the object
+ * @return send interface
+ */
 StreamPassInterface * BConnection_SendAsync_GetIf (BConnection *o);
 
+/**
+ * Initializes the receive interface for the connection.
+ * The receive interface must not be initialized.
+ * 
+ * @param o the object
+ */
 void BConnection_RecvAsync_Init (BConnection *o);
+
+/**
+ * Frees the receive interface for the connection.
+ * The receive interface must be initialized.
+ * If the receive interface was busy when this is called, the connection is no longer usable and must be
+ * freed before any further I/O or interface initialization.
+ * 
+ * @param o the object
+ */
 void BConnection_RecvAsync_Free (BConnection *o);
+
+/**
+ * Returns the receive interface.
+ * The receive interface must be initialized.
+ * 
+ * @param o the object
+ * @return receive interface
+ */
 StreamRecvInterface * BConnection_RecvAsync_GetIf (BConnection *o);