CADET MQ API documentation improvements

1 files changed, 19 insertions, 23 deletions

diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h
index 99d74f223..1b3aac7c9 100644
--- a/src/include/gnunet_cadet_service.h
+++ b/src/include/gnunet_cadet_service.h
@@ -697,26 +697,26 @@ GC_u2h (uint32_t port);
 /******************************************************************************/
 
 /**
- * Method called whenever a given peer connects in MQ-based CADET.
+ * Method called whenever a peer connects to a port in MQ-based CADET.
  *
- * @param cls Closure from @a GNUNET_CADET_open_porT.
+ * @param cls Closure from #GNUNET_CADET_open_porT.
  * @param channel New handle to the channel.
  * @param source Peer that started this channel.
- *
- * @return Closure for the incoming channel. It's given to:
- *         - The @a GNUNET_CADET_DisconnectEventHandler when the channel dies.
- *         - Each the @a GNUNET_MQ_MessageCallback for each message.
+ * @return Closure for the incoming @a channel. It's given to:
+ *         - The #GNUNET_CADET_DisconnectEventHandler (given to
+ *           #GNUNET_CADET_open_porT) when the channel dies.
+ *         - Each the #GNUNET_MQ_MessageCallback handlers for each message
+ *           received on the @a channel.
  */
 typedef void *
 (*GNUNET_CADET_ConnectEventHandler) (void *cls,
                                      struct GNUNET_CADET_Channel *channel,
                                      const struct GNUNET_PeerIdentity *source);
 
-
 /**
  * Function called whenever an MQ-channel is destroyed, even if the destruction
- * was requested by @a GNUNET_CADET_channel_destroy.
- * It must NOT call @a GNUNET_CADET_channel_destroy on the channel.
+ * was requested by #GNUNET_CADET_channel_destroy.
+ * It must NOT call #GNUNET_CADET_channel_destroy on the channel.
  *
  * It should clean up any associated state, including cancelling any pending
  * transmission on this channel.
@@ -728,7 +728,6 @@ typedef void
 (*GNUNET_CADET_DisconnectEventHandler) (void *cls,
                                         const struct GNUNET_CADET_Channel *channel);
 
-
 /**
  * Function called whenever an MQ-channel's transmission window size changes.
  *
@@ -736,29 +735,27 @@ typedef void
  * and will mean the channel is connected to the destination.
  *
  * For an incoming channel it will be called immediately after the
- * @a GNUNET_CADET_ConnectEventHandler, also with a non-zero value.
+ * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value.
  *
  * @param cls Channel closure.
  * @param channel Connection to the other end (henceforth invalid).
- * @param window_size New window size.
+ * @param window_size New window size. If the is more messages than buffer size
+ *                    this value will be negative..
  */
 typedef void
 (*GNUNET_CADET_WindowSizeEventHandler) (void *cls,
                                         const struct GNUNET_CADET_Channel *channel,
                                         int window_size);
 
-
 /**
  * Connect to the MQ-based cadet service.
  *
  * @param cfg Configuration to use.
- *
  * @return Handle to the cadet service NULL on error.
  */
 struct GNUNET_CADET_Handle *
 GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
-
 /**
  * Open a port to receive incomming MQ-based channels.
  *
@@ -767,21 +764,20 @@ GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg);
  * @param connects Function called when an incoming channel is connected.
  * @param connects_cls Closure for the @a connects handler.
  * @param window_changes Function called when the transmit window size changes.
+ *                       Can be NULL.
  * @param disconnects Function called when a channel is disconnected.
  * @param handlers Callbacks for messages we care about, NULL-terminated.
- *
  * @return Port handle.
  */
 struct GNUNET_CADET_Port *
 GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h,
                         const struct GNUNET_HashCode *port,
                         GNUNET_CADET_ConnectEventHandler connects,
-                        void * connects_cls,
+                        void *connects_cls,
                         GNUNET_CADET_WindowSizeEventHandler window_changes,
                         GNUNET_CADET_DisconnectEventHandler disconnects,
                         const struct GNUNET_MQ_MessageHandler *handlers);
 
-
 /**
  * Create a new channel towards a remote peer.
  *
@@ -791,15 +787,17 @@ GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h,
  *
  * @param h CADET handle.
  * @param channel_cls Closure for the channel. It's given to:
+ *                    - The management handler @a window_changes.
  *                    - The disconnect handler @a disconnects
  *                    - Each message type callback in @a handlers
  * @param destination Peer identity the channel should go to.
  * @param port Identification of the destination port.
  * @param options CadetOption flag field, with all desired option bits set to 1.
  * @param window_changes Function called when the transmit window size changes.
+ *                       Can be NULL if this data is of no interest.
+ * TODO                  Not yet implemented.
  * @param disconnects Function called when the channel is disconnected.
  * @param handlers Callbacks for messages we care about, NULL-terminated.
- *
  * @return Handle to the channel.
  */
 struct GNUNET_CADET_Channel *
@@ -812,13 +810,11 @@ GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h,
                              GNUNET_CADET_DisconnectEventHandler disconnects,
                              const struct GNUNET_MQ_MessageHandler *handlers);
 
-
 /**
- * Obtain the message queue for a connected peer.
+ * Obtain the message queue for a connected channel.
  *
  * @param channel The channel handle from which to get the MQ.
- *
- * @return NULL if @a channel is not yet connected.
+ * @return The message queue of the channel.
  */
 struct GNUNET_MQ_Handle *
 GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel);