9 files changed, 30 insertions, 20 deletions

diff --git a/src/transport/gnunet-nat-client-udp.c b/src/transport/gnunet-nat-client-udp.c
index c17710b61..f594db20a 100644
--- a/src/transport/gnunet-nat-client-udp.c
+++ b/src/transport/gnunet-nat-client-udp.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file src/transport/client-test.c
+ * @file src/transport/gnunet-nat-client-udp.c
  * @brief Test for NAT traversal using ICMP method.
  * @author Christian Grothoff
  */
diff --git a/src/transport/gnunet-nat-server-udp.c b/src/transport/gnunet-nat-server-udp.c
index 693adbcf5..b1d221294 100644
--- a/src/transport/gnunet-nat-server-udp.c
+++ b/src/transport/gnunet-nat-server-udp.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file src/transport/server-test.c
+ * @file src/transport/gnunet-nat-server-udp.c
  * @brief Test for NAT traversal using ICMP method.
  * @author Christian Grothoff
  */
diff --git a/src/transport/gnunet-service-transport.c b/src/transport/gnunet-service-transport.c
index 3fbbc8804..e206da43e 100644
--- a/src/transport/gnunet-service-transport.c
+++ b/src/transport/gnunet-service-transport.c
@@ -1844,11 +1844,11 @@ check_pending_validation (void *cls,
  * (otherwise we may be seeing a MiM attack).
  *
  * @param cls closure
- * @param name name of the transport that generated the address
+ * @param message the pong message
  * @param peer who responded to our challenge
- * @param challenge the challenge number we presumably used
  * @param sender_addr string describing our sender address (as observed
- *         by the other peer in human-readable format)
+ *         by the other peer in binary format)
+ * @param sender_address_len number of bytes in 'sender_address'
  */
 static void
 handle_pong (void *cls, const struct GNUNET_MessageHeader *message,
@@ -2215,7 +2215,7 @@ add_to_foreign_address_list (void *cls,
  *
  * @param cls closure
  * @param peer id of the peer, NULL for last call
- * @param hello hello message for the peer (can be NULL)
+ * @param h hello message for the peer (can be NULL)
  * @param trust amount of trust we have in the peer (not used)
  */
 static void
diff --git a/src/transport/gnunet-service-transport_blacklist.c b/src/transport/gnunet-service-transport_blacklist.c
index 6b90929f1..8f78f498f 100644
--- a/src/transport/gnunet-service-transport_blacklist.c
+++ b/src/transport/gnunet-service-transport_blacklist.c
@@ -250,6 +250,7 @@ GNUNET_TRANSPORT_blacklist_check (const struct GNUNET_PeerIdentity *id)
 /**
  * Initialize the blacklisting subsystem.
  *
+ * @param server server of the transport service
  * @param s scheduler to use
  */
 void 
diff --git a/src/transport/plugin_transport.h b/src/transport/plugin_transport.h
index e00c97799..2630ffbad 100644
--- a/src/transport/plugin_transport.h
+++ b/src/transport/plugin_transport.h
@@ -171,7 +171,8 @@ typedef void
  *
  * @param cls closure
  * @param target who should receive this message
- * @param msg the message to transmit
+ * @param msgbuf the message to transmit
+ * @param msgbuf_size number of bytes in 'msgbuf'
  * @param priority how important is the message (most plugins will
  *                 ignore message priority and just FIFO)
  * @param timeout how long to wait at most for the transmission (does not
diff --git a/src/transport/plugin_transport_tcp.c b/src/transport/plugin_transport_tcp.c
index 05a7c2eb0..7135d5ddc 100644
--- a/src/transport/plugin_transport_tcp.c
+++ b/src/transport/plugin_transport_tcp.c
@@ -557,6 +557,7 @@ disconnect_session (struct Session *session)
  * @param cls closure
  * @param target who should receive this message
  * @param msg the message to transmit
+ * @param msgbuf_size number of bytes in 'msg'
  * @param priority how important is the message (most plugins will
  *                 ignore message priority and just FIFO)
  * @param timeout how long to wait at most for the transmission (does not
diff --git a/src/transport/plugin_transport_template.c b/src/transport/plugin_transport_template.c
index bac9bcd82..fc1c1722b 100644
--- a/src/transport/plugin_transport_template.c
+++ b/src/transport/plugin_transport_template.c
@@ -136,13 +136,23 @@ struct Plugin
  * @param cls closure
  * @param target who should receive this message
  * @param priority how important is the message
- * @param msg the message to transmit
+ * @param msgbuf the message to transmit
+ * @param msgbuf_size number of bytes in 'msgbuf'
  * @param timeout when should we time out 
+ * @param addr the address to use (can be NULL if the plugin
+ *                is "on its own" (i.e. re-use existing TCP connection))
+ * @param addrlen length of the address in bytes
+ * @param force_address GNUNET_YES if the plugin MUST use the given address,
+ *                otherwise the plugin may use other addresses or
+ *                existing connections (if available)
  * @param cont continuation to call once the message has
  *        been transmitted (or if the transport is ready
  *        for the next transmission call; or if the
  *        peer disconnected...)
  * @param cont_cls closure for cont
+ * @return number of bytes used (on the physical network, with overheads);
+ *         -1 on hard errors (i.e. address invalid); 0 is a legal value
+ *         and does NOT mean that the message was not transmitted (DV)
  */
 static ssize_t
 template_plugin_send (void *cls,
diff --git a/src/transport/plugin_transport_udp.c b/src/transport/plugin_transport_udp.c
index 94222bd6d..be8e2848c 100644
--- a/src/transport/plugin_transport_udp.c
+++ b/src/transport/plugin_transport_udp.c
@@ -75,8 +75,6 @@ struct UDPMessage
 
 };
 
-/* Forward definition */
-struct Plugin;
 
 struct PrettyPrinterContext
 {
@@ -111,6 +109,11 @@ struct Plugin
   struct GNUNET_RESOLVER_RequestHandle *hostname_dns;
 
   /**
+   * FD Read set
+   */
+  struct GNUNET_NETWORK_FDSet *rs;
+
+  /**
    * ID of task used to update our addresses when one expires.
    */
   GNUNET_SCHEDULER_TaskIdentifier address_update_task;
@@ -131,11 +134,6 @@ struct Plugin
    */
   uint16_t adv_port;
 
-  /*
-   * FD Read set
-   */
-  struct GNUNET_NETWORK_FDSet *rs;
-
 };
 
 /* *********** globals ************* */
@@ -148,13 +146,14 @@ static struct GNUNET_NETWORK_Handle *udp_sock;
 /**
  * Disconnect from a remote node.
  *
- * @param tsession the session that is closed
+ * @param cls closure ('struct Plugin'), unused
+ * @param target peer do disconnect
  * @return GNUNET_OK on success, GNUNET_SYSERR if the operation failed
  */
 void
 udp_disconnect (void *cls, const struct GNUNET_PeerIdentity *target)
 {
-  return;
+  /* nothing to do, UDP is stateless */
 }
 
 /**
@@ -187,7 +186,7 @@ udp_transport_server_stop (void *cls)
  * @param cls closure
  * @param target who should receive this message (ignored by UDP)
  * @param msgbuf one or more GNUNET_MessageHeader(s) strung together
- * @param msgbufsize the size of the msgbuf to send
+ * @param msgbuf_size the size of the msgbuf to send
  * @param priority how important is the message (ignored by UDP)
  * @param timeout when should we time out (give up) if we can not transmit?
  * @param addr the addr to send the message to, needs to be a sockaddr for us
diff --git a/src/transport/transport_api.c b/src/transport/transport_api.c
index 9e326c9aa..b98cabf0b 100644
--- a/src/transport/transport_api.c
+++ b/src/transport/transport_api.c
@@ -897,7 +897,6 @@ GNUNET_TRANSPORT_set_quota (struct GNUNET_TRANSPORT_Handle *handle,
  * Obtain the HELLO message for this peer.
  *
  * @param handle connection to transport service
- * @param timeout how long to wait for the HELLO
  * @param rec function to call with the HELLO, sender will be our peer
  *            identity; message and sender will be NULL on timeout
  *            (handshake with transport service pending/failed).
@@ -1059,7 +1058,6 @@ send_start (void *cls, size_t size, void *buf)
 /**
  * Free neighbour. 
  * 
- * @param h our state
  * @param n the entry to free
  */
 static void