fixing doxygen warnings

18 files changed, 61 insertions, 28 deletions

diff --git a/src/core/core_api_peer_request.c b/src/core/core_api_peer_request.c
index 008393227..ec5fae32b 100644
--- a/src/core/core_api_peer_request.c
+++ b/src/core/core_api_peer_request.c
@@ -130,6 +130,7 @@ send_request (void *cls,
  * @param sched scheduler to use
  * @param cfg configuration to use
  * @param timeout how long to try to talk to core
+ * @param peer who should we connect to
  * @param cont function to call once the request has been completed (or timed out)
  * @param cont_cls closure for cont
  * @return NULL on error (cont will not be called), otherwise handle for cancellation
diff --git a/src/fs/gnunet-service-fs.c b/src/fs/gnunet-service-fs.c
index ffda521dd..11ab41582 100644
--- a/src/fs/gnunet-service-fs.c
+++ b/src/fs/gnunet-service-fs.c
@@ -1083,7 +1083,7 @@ test_load_too_high ()
  * at transmitting a query to a peer.  
  *
  * @param cls the requests "struct PendingRequest*"
- * @param pid ID of receiving peer, 0 on transmission error
+ * @param tpid ID of receiving peer, 0 on transmission error
  */
 static void
 transmit_query_continuation (void *cls,
@@ -1414,7 +1414,7 @@ forward_request_task (void *cls,
  * at transmitting a reply to a peer.  
  *
  * @param cls the requests "struct PendingRequest*"
- * @param pid ID of receiving peer, 0 on transmission error
+ * @param tpid ID of receiving peer, 0 on transmission error
  */
 static void
 transmit_reply_continuation (void *cls,
@@ -2498,7 +2498,6 @@ static struct GNUNET_SERVER_MessageHandler handlers[] = {
 /**
  * Process fs requests.
  *
- * @param cls closure
  * @param s scheduler to use
  * @param server the initialized server
  * @param c configuration to use
diff --git a/src/fs/gnunet-service-fs_drq.c b/src/fs/gnunet-service-fs_drq.c
index cb941c72b..29b2dca82 100644
--- a/src/fs/gnunet-service-fs_drq.c
+++ b/src/fs/gnunet-service-fs_drq.c
@@ -300,6 +300,15 @@ struct GetClosure
  * complete.
  *
  * @param cls our 'struct GetClosure*'
+ * @param key key for the content
+ * @param size number of bytes in data
+ * @param data content stored
+ * @param type type of the content
+ * @param priority priority of the content
+ * @param anonymity anonymity-level for the content
+ * @param expiration expiration time for the content
+ * @param uid unique identifier for the datum;
+ *        maybe 0 if no unique identifier is available
  */
 static void
 get_iterator (void *cls,
diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h
index bc72e2e09..204d3d6ab 100644
--- a/src/include/gnunet_container_lib.h
+++ b/src/include/gnunet_container_lib.h
@@ -243,7 +243,7 @@ GNUNET_CONTAINER_meta_data_test_equal (const struct
  *
  * @param md metadata to extend
  * @param plugin_name name of the plugin that produced this value;
- *        special values can be used (i.e. '<zlib>' for zlib being
+ *        special values can be used (i.e. '&lt;zlib&gt;' for zlib being
  *        used in the main libextractor library and yielding
  *        meta data).
  * @param type libextractor-type describing the meta data
diff --git a/src/include/gnunet_core_service.h b/src/include/gnunet_core_service.h
index af431ba56..060a0f8ee 100644
--- a/src/include/gnunet_core_service.h
+++ b/src/include/gnunet_core_service.h
@@ -240,6 +240,7 @@ struct GNUNET_CORE_PeerRequestHandle;
  * @param sched scheduler to use
  * @param cfg configuration to use
  * @param timeout how long to try to talk to core
+ * @param peer who should we connect to
  * @param cont function to call once the request has been completed (or timed out)
  * @param cont_cls closure for cont
  * @return NULL on error (cont will not be called), otherwise handle for cancellation
diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h
index f4ede1384..7b6898293 100644
--- a/src/include/gnunet_disk_lib.h
+++ b/src/include/gnunet_disk_lib.h
@@ -340,9 +340,11 @@ int GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p);
  *
  * @param p pipe to close end of
  * @param end which end of the pipe to close
+ * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
  */
 int
-GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p, enum GNUNET_DISK_PipeEnd end);
+GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p, 
+                            enum GNUNET_DISK_PipeEnd end);
 
 /**
  * Close an open file.
@@ -355,6 +357,7 @@ int GNUNET_DISK_file_close (struct GNUNET_DISK_FileHandle *h);
 
 /**
  * Get the handle to a particular pipe end
+ *
  * @param p pipe
  * @param n end to access
  * @return handle for the respective end
diff --git a/src/include/gnunet_os_lib.h b/src/include/gnunet_os_lib.h
index 02d1063f7..32d9dc7ff 100644
--- a/src/include/gnunet_os_lib.h
+++ b/src/include/gnunet_os_lib.h
@@ -196,7 +196,9 @@ int GNUNET_OS_set_process_priority (pid_t proc,
  * @return process ID of the new process, -1 on error
  */
 pid_t
-GNUNET_OS_start_process (struct GNUNET_DISK_PipeHandle *pipe_stdin, struct GNUNET_DISK_PipeHandle *pipe_stdout, const char *filename, ...);
+GNUNET_OS_start_process (struct GNUNET_DISK_PipeHandle *pipe_stdin, 
+                         struct GNUNET_DISK_PipeHandle *pipe_stdout, 
+                         const char *filename, ...);
 
 
 /**
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
diff --git a/src/util/disk.c b/src/util/disk.c
index 710935516..c1a988464 100644
--- a/src/util/disk.c
+++ b/src/util/disk.c
@@ -1675,10 +1675,12 @@ GNUNET_DISK_pipe (int blocking)
  * Closes an interprocess channel
  *
  * @param p pipe to close
+ * @param end which end of the pipe to close
  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
  */
 int
-GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p, enum GNUNET_DISK_PipeEnd end)
+GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p,
+                            enum GNUNET_DISK_PipeEnd end)
 {
   int ret = GNUNET_OK;
   int save;
@@ -1779,8 +1781,10 @@ GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p)
 
 /**
  * Get the handle to a particular pipe end
+ *
  * @param p pipe
  * @param n end to access
+ * @return handle for the respective end
  */
 const struct GNUNET_DISK_FileHandle *
 GNUNET_DISK_pipe_handle (const struct GNUNET_DISK_PipeHandle *p,
diff --git a/src/util/os_priority.c b/src/util/os_priority.c
index 547d6cd8a..d501b3511 100644
--- a/src/util/os_priority.c
+++ b/src/util/os_priority.c
@@ -119,12 +119,16 @@ GNUNET_OS_set_process_priority (pid_t proc,
 /**
  * Start a process.
  *
+ * @param pipe_stdin pipe to use to send input to child process (or NULL)
+ * @param pipe_stdout pipe to use to get output from child process (or NULL)
  * @param filename name of the binary
  * @param ... NULL-terminated list of arguments to the process
  * @return process ID of the new process, -1 on error
  */
 pid_t
-GNUNET_OS_start_process (struct GNUNET_DISK_PipeHandle *pipe_stdin, struct GNUNET_DISK_PipeHandle *pipe_stdout, const char *filename, ...)
+GNUNET_OS_start_process (struct GNUNET_DISK_PipeHandle *pipe_stdin, 
+                         struct GNUNET_DISK_PipeHandle *pipe_stdout,
+                         const char *filename, ...)
 {
   /* FIXME:  Make this work on windows!!! */
   va_list ap;