-DOC: First pass of new workflow over CADET subsystem.

10 files changed, 30 insertions, 217 deletions

diff --git a/src/cadet/gnunet-service-cadet_channel.c b/src/cadet/gnunet-service-cadet_channel.c
index 9a2180cc1..f742ba4a7 100644
--- a/src/cadet/gnunet-service-cadet_channel.c
+++ b/src/cadet/gnunet-service-cadet_channel.c
@@ -388,11 +388,6 @@ struct CadetChannel
 
 };
 
-/**
- * Assign type of message to drop.
- * @param ch CadetChannel to assign type to drop.
- * @param message GNUNET_CADET_RequestDropCadetMessage to get the type from.
- */
 void
 GCCH_assign_type_to_drop (struct CadetChannel *ch, const struct
                           GNUNET_CADET_RequestDropCadetMessage *message)
@@ -660,16 +655,6 @@ GCCH_tunnel_up (struct CadetChannel *ch)
 }
 
 
-/**
- * Create a new channel.
- *
- * @param owner local client owning the channel
- * @param ccn local number of this channel at the @a owner
- * @param destination peer to which we should build the channel
- * @param port desired port at @a destination
- * @param options options for the channel
- * @return handle to the new channel
- */
 struct CadetChannel *
 GCCH_channel_local_new (struct CadetClient *owner,
                         struct GNUNET_CADET_ClientChannelNumber ccn,
@@ -756,15 +741,6 @@ timeout_closed_cb (void *cls)
 }
 
 
-/**
- * Create a new channel based on a request coming in over the network.
- *
- * @param t tunnel to the remote peer
- * @param ctn identifier of this channel in the tunnel
- * @param h_port desired hash of local port
- * @param options options for the channel
- * @return handle to the new channel
- */
 struct CadetChannel *
 GCCH_channel_incoming_new (struct CadetTunnel *t,
                            struct GNUNET_CADET_ChannelTunnelNumber ctn,
@@ -960,15 +936,6 @@ send_ack_to_client (struct CadetChannel *ch, int to_owner)
 }
 
 
-/**
- * A client is bound to the port that we have a channel
- * open to.  Send the acknowledgement for the connection
- * request and establish the link with the client.
- *
- * @param ch open incoming channel
- * @param c client listening on the respective @a port
- * @param port the port @a is listening on
- */
 void
 GCCH_bind (struct CadetChannel *ch,
            struct CadetClient *c,
@@ -1126,15 +1093,6 @@ GCCH_channel_local_destroy (struct CadetChannel *ch,
 }
 
 
-/**
- * We got an acknowledgement for the creation of the channel
- * (the port is open on the other side).  Verify that the
- * other end really has the right port, and begin transmissions.
- *
- * @param ch channel to destroy
- * @param cti identifier of the connection that delivered the message
- * @param port port number (needed to verify receiver knows the port)
- */
 void
 GCCH_handle_channel_open_ack (
   struct CadetChannel *ch,
@@ -1227,14 +1185,6 @@ is_before (void *cls,
 }
 
 
-/**
- * We got payload data for a channel.  Pass it on to the client
- * and send an ACK to the other end (once flow control allows it!)
- *
- * @param ch channel that got data
- * @param cti identifier of the connection that delivered the message
- * @param msg message that was received
- */
 void
 GCCH_handle_channel_plaintext_data (
   struct CadetChannel *ch,
@@ -1657,15 +1607,6 @@ GCCH_handle_channel_plaintext_data_ack (
 }
 
 
-/**
- * Destroy channel, based on the other peer closing the
- * connection.  Also needs to remove this channel from
- * the tunnel.
- *
- * @param ch channel to destroy
- * @param cti identifier of the connection that delivered the message,
- *            NULL if we are simulating receiving a destroy due to shutdown
- */
 void
 GCCH_handle_remote_destroy (
   struct CadetChannel *ch,
@@ -1916,13 +1857,6 @@ GCCH_handle_local_data (struct CadetChannel *ch,
 }
 
 
-/**
- * Handle ACK from client on local channel.  Means the client is ready
- * for more data, see if we have any for it.
- *
- * @param ch channel to destroy
- * @param client_ccn ccn of the client sending the ack
- */
 void
 GCCH_handle_local_ack (struct CadetChannel *ch,
                        struct GNUNET_CADET_ClientChannelNumber client_ccn)
diff --git a/src/cadet/gnunet-service-cadet_channel.h b/src/cadet/gnunet-service-cadet_channel.h
index 6d691cafc..b09de883f 100644
--- a/src/cadet/gnunet-service-cadet_channel.h
+++ b/src/cadet/gnunet-service-cadet_channel.h
@@ -67,7 +67,7 @@ GCCH_is_type_to_drop (struct CadetChannel *ch, const struct
                       GNUNET_MessageHeader *message);
 
 /**
- * Check if type of message is the one to drop.
+ * Assign type of message to drop.
  * @param ch CadetChannel to assign type to drop.
  * @param message GNUNET_CADET_RequestDropCadetMessage to get the type from.
  */
@@ -174,7 +174,6 @@ GCCH_tunnel_up (struct CadetChannel *ch);
  *
  * @param t tunnel to the remote peer
  * @param chid identifier of this channel in the tunnel
- * @param origin peer to who initiated the channel
  * @param h_port hash of desired local port
  * @param options options for the channel
  * @return handle to the new channel
@@ -201,7 +200,8 @@ GCCH_handle_duplicate_open (struct CadetChannel *ch,
 
 
 /**
- * We got payload data for a channel.  Pass it on to the client.
+ * We got payload data for a channel.  Pass it on to the client
+ * and send an ACK to the other end (once flow control allows it!)
  *
  * @param ch channel that got data
  * @param cti identifier of the connection that delivered the message
@@ -234,7 +234,8 @@ GCCH_handle_channel_plaintext_data_ack (struct CadetChannel *ch,
 
 /**
  * We got an acknowledgement for the creation of the channel
- * (the port is open on the other side). Begin transmissions.
+ * (the port is open on the other side).  Verify that the
+ * other end really has the right port, and begin transmissions.
  *
  * @param ch channel to destroy
  * @param cti identifier of the connection that delivered the message,
@@ -262,7 +263,7 @@ GCCH_handle_channel_open_ack (struct CadetChannel *ch,
  *
  * @param ch channel to destroy
  * @param cti identifier of the connection that delivered the message,
- *            NULL during shutdown
+ *            NULL if we are simulating receiving a destroy due to shutdown
  */
 void
 GCCH_handle_remote_destroy (struct CadetChannel *ch,
@@ -292,7 +293,8 @@ GCCH_handle_local_data (struct CadetChannel *ch,
 
 
 /**
- * Handle ACK from client on local channel.
+ * Handle ACK from client on local channel.  Means the client is ready
+ * for more data, see if we have any for it.
  *
  * @param ch channel to destroy
  * @param client_ccn ccn of the client sending the ack
diff --git a/src/cadet/gnunet-service-cadet_connection.c b/src/cadet/gnunet-service-cadet_connection.c
index 637e8663b..66b67aa64 100644
--- a/src/cadet/gnunet-service-cadet_connection.c
+++ b/src/cadet/gnunet-service-cadet_connection.c
@@ -449,14 +449,6 @@ GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid)
 }
 
 
-/**
- * We observed some the given @a latency on the connection
- * identified by @a cti.  (The same connection was taken
- * in both directions.)
- *
- * @param cid connection identifier where we measured latency
- * @param latency the observed latency
- */
 void
 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
                       struct GNUNET_TIME_Relative latency)
@@ -484,13 +476,6 @@ GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 }
 
 
-/**
- * A #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE_ACK was received for
- * this connection, implying that the end-to-end connection is up.
- * Process it.
- *
- * @param cc the connection that got the ACK.
- */
 void
 GCC_handle_connection_create_ack (struct CadetConnection *cc)
 {
@@ -943,18 +928,6 @@ GCC_create_inbound (struct CadetPeer *destination,
 }
 
 
-/**
- * Create a connection to @a destination via @a path and
- * notify @a cb whenever we are ready for more data.
- *
- * @param destination where to go
- * @param path which path to take (may not be the full path)
- * @param off offset of @a destination on @a path
- * @param ct tunnel that uses the connection
- * @param ready_cb function to call when ready to transmit
- * @param ready_cb_cls closure for @a cb
- * @return handle to the connection
- */
 struct CadetConnection *
 GCC_create (struct CadetPeer *destination,
             struct CadetPeerPath *path,
diff --git a/src/cadet/gnunet-service-cadet_connection.h b/src/cadet/gnunet-service-cadet_connection.h
index d646b3dc2..53c0c1541 100644
--- a/src/cadet/gnunet-service-cadet_connection.h
+++ b/src/cadet/gnunet-service-cadet_connection.h
@@ -142,7 +142,9 @@ GCC_transmit (struct CadetConnection *cc,
 
 
 /**
- * A CREATE_ACK was received for this connection, process it.
+ * A #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE_ACK was received for
+ * this connection, implying that the end-to-end connection is up.
+ * Process it.
  *
  * @param cc the connection that got the ACK.
  */
diff --git a/src/cadet/gnunet-service-cadet_paths.c b/src/cadet/gnunet-service-cadet_paths.c
index aa31aaa74..83b996e05 100644
--- a/src/cadet/gnunet-service-cadet_paths.c
+++ b/src/cadet/gnunet-service-cadet_paths.c
@@ -594,13 +594,6 @@ GCPP_try_path_from_dht (const struct GNUNET_DHT_PathElement *get_path,
 }
 
 
-/**
- * We got an incoming connection, obtain the corresponding path.
- *
- * @param path_length number of segments on the @a path
- * @param pids path through the network, in reverse order (we are at the end at index @a path_length)
- * @return corresponding path object
- */
 struct CadetPeerPath *
 GCPP_get_path_from_route (unsigned int path_length,
                           const struct GNUNET_PeerIdentity *pids)
@@ -723,13 +716,6 @@ GCPP_find_peer (struct CadetPeerPath *path,
 }
 
 
-/**
- * Obtain the peer at offset @a off in @a path.
- *
- * @param path peer path to inspect
- * @param off offset to return, must be smaller than path length
- * @return the peer at offset @a off
- */
 struct CadetPeer *
 GCPP_get_peer_at_offset (struct CadetPeerPath *path,
                          unsigned int off)
diff --git a/src/cadet/gnunet-service-cadet_paths.h b/src/cadet/gnunet-service-cadet_paths.h
index afd193596..defdd0df2 100644
--- a/src/cadet/gnunet-service-cadet_paths.h
+++ b/src/cadet/gnunet-service-cadet_paths.h
@@ -53,7 +53,8 @@ GCPP_try_path_from_dht (const struct GNUNET_DHT_PathElement *get_path,
  * We got an incoming connection, obtain the corresponding path.
  *
  * @param path_length number of segments on the @a path
- * @param path through the network, in reverse order (we are at the end!)
+ * @param path through the network, in reverse order 
+ *  (we are at the end, at index @a path_length)
  * @return corresponding path object
  */
 struct CadetPeerPath *
diff --git a/src/cadet/gnunet-service-cadet_peer.c b/src/cadet/gnunet-service-cadet_peer.c
index 2437a3e1b..99669eb05 100644
--- a/src/cadet/gnunet-service-cadet_peer.c
+++ b/src/cadet/gnunet-service-cadet_peer.c
@@ -260,21 +260,6 @@ GCP_2s (const struct CadetPeer *cp)
 }
 
 
-/**
- * Calculate how desirable a path is for @a cp if @a cp
- * is at offset @a off.
- *
- * The 'desirability_table.c' program can be used to compute a list of
- * sample outputs for different scenarios.  Basically, we score paths
- * lower if there are many alternatives, and higher if they are
- * shorter than average, and very high if they are much shorter than
- * average and without many alternatives.
- *
- * @param cp a peer reachable via a path
- * @param off offset of @a cp in the path
- * @return score how useful a path is to reach @a cp,
- *         positive scores mean path is more desirable
- */
 double
 GCP_get_desirability_of_path (struct CadetPeer *cp,
                               unsigned int off)
@@ -965,17 +950,6 @@ path_heap_cleanup (void *cls)
 }
 
 
-/**
- * Try adding a @a path to this @a peer.  If the peer already
- * has plenty of paths, return NULL.
- *
- * @param cp peer to which the @a path leads to
- * @param path a path looking for an owner; may not be fully initialized yet!
- * @param off offset of @a cp in @a path
- * @param force force attaching the path
- * @return NULL if this peer does not care to become a new owner,
- *         otherwise the node in the peer's path heap for the @a path.
- */
 struct GNUNET_CONTAINER_HeapNode *
 GCP_attach_path (struct CadetPeer *cp,
                  struct CadetPeerPath *path,
@@ -1287,16 +1261,6 @@ GCP_iterate_indirect_paths (struct CadetPeer *cp,
 }
 
 
-/**
- * Iterate over the paths to @a cp where
- * @a cp is at distance @a dist from us.
- *
- * @param cp Peer to get path info.
- * @param dist desired distance of @a cp to us on the path
- * @param callback Function to call for every path.
- * @param callback_cls Closure for @a callback.
- * @return Number of iterated paths.
- */
 unsigned int
 GCP_iterate_paths_at (struct CadetPeer *cp,
                       unsigned int dist,
@@ -1365,13 +1329,6 @@ hello_offer_done (void *cls)
 }
 
 
-/**
- * We got a HELLO for a @a peer, remember it, and possibly
- * trigger adequate actions (like trying to connect).
- *
- * @param cp the peer we got a HELLO for
- * @param hello the HELLO to remember
- */
 void
 GCP_set_hello (struct CadetPeer *cp,
                const struct GNUNET_HELLO_Message *hello)
diff --git a/src/cadet/gnunet-service-cadet_peer.h b/src/cadet/gnunet-service-cadet_peer.h
index 7a39615ff..69436d766 100644
--- a/src/cadet/gnunet-service-cadet_peer.h
+++ b/src/cadet/gnunet-service-cadet_peer.h
@@ -62,6 +62,12 @@ GCP_get (const struct GNUNET_PeerIdentity *peer_id,
  * Calculate how desirable a path is for @a cp if
  * @a cp is at offset @a off in the path.
  *
+ * The 'desirability_table.c' program can be used to compute a list of
+ * sample outputs for different scenarios.  Basically, we score paths
+ * lower if there are many alternatives, and higher if they are
+ * shorter than average, and very high if they are much shorter than
+ * average and without many alternatives.
+ *
  * @param cp a peer reachable via a path
  * @param off offset of @a cp in a path
  * @return score how useful a path is to reach @a cp,
@@ -229,7 +235,7 @@ GCP_drop_tunnel (struct CadetPeer *cp,
  * @param cp peer to which the @a path leads to
  * @param path a path looking for an owner; may not be fully initialized yet!
  * @param off offset of @a cp in @a path
- * @param force for attaching the path
+ * @param force force attaching the path
  * @return NULL if this peer does not care to become a new owner,
  *         otherwise the node in the peer's path heap for the @a path.
  */
diff --git a/src/cadet/gnunet-service-cadet_tunnels.c b/src/cadet/gnunet-service-cadet_tunnels.c
index cabbeed0c..9653fd3ec 100644
--- a/src/cadet/gnunet-service-cadet_tunnels.c
+++ b/src/cadet/gnunet-service-cadet_tunnels.c
@@ -576,13 +576,6 @@ GCT_get_destination (struct CadetTunnel *t)
 }
 
 
-/**
- * Count channels of a tunnel.
- *
- * @param t Tunnel on which to count.
- *
- * @return Number of channels.
- */
 unsigned int
 GCT_count_channels (struct CadetTunnel *t)
 {
@@ -606,13 +599,6 @@ lookup_channel (struct CadetTunnel *t,
 }
 
 
-/**
- * Count all created connections of a tunnel. Not necessarily ready connections!
- *
- * @param t Tunnel on which to count.
- *
- * @return Number of connections created, either being established or ready.
- */
 unsigned int
 GCT_count_any_connections (const struct CadetTunnel *t)
 {
@@ -1706,14 +1692,6 @@ retry_kx (void *cls)
 }
 
 
-/**
- * Handle KX message that lacks authentication (and which will thus
- * only be considered authenticated after we respond with our own
- * KX_AUTH and finally successfully decrypt payload).
- *
- * @param ct connection/tunnel combo that received encrypted message
- * @param msg the key exchange message
- */
 void
 GCT_handle_kx (struct CadetTConnection *ct,
                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg)
@@ -2839,14 +2817,6 @@ maintain_connections_cb (void *cls)
 }
 
 
-/**
- * Consider using the path @a p for the tunnel @a t.
- * The tunnel destination is at offset @a off in path @a p.
- *
- * @param cls our tunnel
- * @param path a path to our destination
- * @param off offset of the destination on path @a path
- */
 void
 GCT_consider_path (struct CadetTunnel *t,
                    struct CadetPeerPath *p,
@@ -3216,16 +3186,6 @@ GCT_create_tunnel (struct CadetPeer *destination)
 }
 
 
-/**
- * Add a @a connection to the @a tunnel.
- *
- * @param t a tunnel
- * @param cid connection identifier to use for the connection
- * @param options options for the connection
- * @param path path to use for the connection
- * @return #GNUNET_OK on success,
- *         #GNUNET_SYSERR on failure (duplicate connection)
- */
 int
 GCT_add_inbound_connection (struct CadetTunnel *t,
                             const struct
@@ -3449,17 +3409,6 @@ GCT_handle_encrypted (struct CadetTConnection *ct,
 }
 
 
-/**
- * Sends an already built message on a tunnel, encrypting it and
- * choosing the best connection if not provided.
- *
- * @param message Message to send. Function modifies it.
- * @param t Tunnel on which this message is transmitted.
- * @param cont Continuation to call once message is really sent.
- * @param cont_cls Closure for @c cont.
- * @param The ID of the channel we are using for sending.
- * @return Handle to cancel message
- */
 struct CadetTunnelQueueEntry *
 GCT_send (struct CadetTunnel *t,
           const struct GNUNET_MessageHeader *message,
diff --git a/src/cadet/gnunet-service-cadet_tunnels.h b/src/cadet/gnunet-service-cadet_tunnels.h
index aea131542..018a3ec73 100644
--- a/src/cadet/gnunet-service-cadet_tunnels.h
+++ b/src/cadet/gnunet-service-cadet_tunnels.h
@@ -252,20 +252,21 @@ GCT_send_cancel (struct CadetTunnelQueueEntry *q);
 
 
 /**
- * Return the number of channels using a tunnel.
+ * Returns the number of channels using a tunnel.
  *
- * @param t tunnel to count obtain the number of channels for
- * @return number of channels using the tunnel
+ * @param t Tunnel in question.
+ * @return Number of channels using the tunnel.
  */
 unsigned int
 GCT_count_channels (struct CadetTunnel *t);
 
 
 /**
- * Return the number of connections available for a tunnel.
+ * Counts the number of connections created for a tunnel,
+ * including busy connections.
  *
- * @param t tunnel to count obtain the number of connections for
- * @return number of connections available for the tunnel
+ * @param t Tunnel to be counted.
+ * @return Number of connections created for the tunnel.
  */
 unsigned int
 GCT_count_any_connections (const struct CadetTunnel *t);
@@ -341,7 +342,9 @@ GCT_change_estate (struct CadetTunnel *t,
                    enum CadetTunnelEState state);
 
 /**
- * Handle KX message.
+ * Handle KX message that lacks authentication (and which will thus
+ * only be considered authenticated after we respond with our own
+ * KX_AUTH and finally successfully decrypt the payload).
  *
  * @param ct connection/tunnel combo that received encrypted message
  * @param msg the key exchange message