BSocksClient: cosmetic changes, documentation

socksclient/BSocksClient.c

@@ -354,9 +354,8 @@ int BSocksClient_Init (BSocksClient *o, BAddr server_addr, BAddr dest_addr, BSoc
     // set state
     o->state = STATE_CONNECTING;
     
-    DebugObject_Init(&o->d_obj);
     DebugError_Init(&o->d_err, BReactor_PendingGroup(o->reactor));
-    
+    DebugObject_Init(&o->d_obj);
     return 1;
     
 fail1:
@@ -367,8 +366,8 @@ fail0:
 
 void BSocksClient_Free (BSocksClient *o)
 {
-    DebugError_Free(&o->d_err);
     DebugObject_Free(&o->d_obj);
+    DebugError_Free(&o->d_err);
     
     if (o->state == STATE_UP) {
         // free up I/O

socksclient/BSocksClient.h

@@ -42,6 +42,18 @@
 #define BSOCKSCLIENT_EVENT_UP 2
 #define BSOCKSCLIENT_EVENT_ERROR_CLOSED 3
 
+/**
+ * Handler for events generated by the SOCKS client.
+ * 
+ * @param user as in {@link BSocksClient_Init}
+ * @param event event type. One of BSOCKSCLIENT_EVENT_ERROR, BSOCKSCLIENT_EVENT_UP
+ *              and BSOCKSCLIENT_EVENT_ERROR_CLOSED.
+ *              If event is BSOCKSCLIENT_EVENT_UP, the object was previously in down
+ *              state and has transitioned to up state; I/O can be done from this point on.
+ *              If event is BSOCKSCLIENT_EVENT_ERROR or BSOCKSCLIENT_EVENT_ERROR_CLOSED,
+ *              the object must be freed from within the job closure of this handler,
+ *              and no further I/O must be attempted.
+ */
 typedef void (*BSocksClient_handler) (void *user, int event);
 
 typedef struct {
@@ -89,13 +101,48 @@ typedef struct {
             StreamSocketSource recv_source;
         } up;
     };
-    DebugObject d_obj;
     DebugError d_err;
+    DebugObject d_obj;
 } BSocksClient;
 
+/**
+ * Initializes the object.
+ * The object is initialized in down state. The object must transition to up
+ * state before the user may begin any I/O.
+ * 
+ * @param o the object
+ * @param server_addr SOCKS5 server address
+ * @param dest_addr remote address
+ * @param handler handler for up and error events
+ * @param user value passed to handler
+ * @param reactor reactor we live in
+ * @return 1 on success, 0 on failure
+ */
 int BSocksClient_Init (BSocksClient *o, BAddr server_addr, BAddr dest_addr, BSocksClient_handler handler, void *user, BReactor *reactor) WARN_UNUSED;
+
+/**
+ * Frees the object.
+ * 
+ * @param o the object
+ */
 void BSocksClient_Free (BSocksClient *o);
+
+/**
+ * Returns the send interface.
+ * The object must be in up state.
+ * 
+ * @param o the object
+ * @return send interface
+ */
 StreamPassInterface * BSocksClient_GetSendInterface (BSocksClient *o);
+
+/**
+ * Returns the receive interface.
+ * The object must be in up state.
+ * 
+ * @param o the object
+ * @return receive interface
+ */
 StreamRecvInterface * BSocksClient_GetRecvInterface (BSocksClient *o);
 
 #endif