[GNUnet-SVN] r10372 - in gnunet/src: core fs include transport util

[gnunet]

Author: grothoff
Date: 2010-02-18 16:07:02 +0100 (Thu, 18 Feb 2010)
New Revision: 10372

Modified:
   gnunet/src/core/core_api_peer_request.c
   gnunet/src/fs/gnunet-service-fs.c
   gnunet/src/fs/gnunet-service-fs_drq.c
   gnunet/src/include/gnunet_container_lib.h
   gnunet/src/include/gnunet_core_service.h
   gnunet/src/include/gnunet_disk_lib.h
   gnunet/src/include/gnunet_os_lib.h
   gnunet/src/transport/gnunet-nat-client-udp.c
   gnunet/src/transport/gnunet-nat-server-udp.c
   gnunet/src/transport/gnunet-service-transport.c
   gnunet/src/transport/gnunet-service-transport_blacklist.c
   gnunet/src/transport/plugin_transport.h
   gnunet/src/transport/plugin_transport_tcp.c
   gnunet/src/transport/plugin_transport_template.c
   gnunet/src/transport/plugin_transport_udp.c
   gnunet/src/transport/transport_api.c
   gnunet/src/util/disk.c
   gnunet/src/util/os_priority.c
Log:
fixing doxygen warnings

Modified: gnunet/src/core/core_api_peer_request.c
===================================================================
--- gnunet/src/core/core_api_peer_request.c     2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/core/core_api_peer_request.c     2010-02-18 15:07:02 UTC (rev 
10372)
@@ -130,6 +130,7 @@
  * @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

Modified: gnunet/src/fs/gnunet-service-fs.c
===================================================================
--- gnunet/src/fs/gnunet-service-fs.c   2010-02-18 14:33:35 UTC (rev 10371)
+++ gnunet/src/fs/gnunet-service-fs.c   2010-02-18 15:07:02 UTC (rev 10372)
@@ -1083,7 +1083,7 @@
  * 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 @@
  * 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 @@
 /**
  * Process fs requests.
  *
- * @param cls closure
  * @param s scheduler to use
  * @param server the initialized server
  * @param c configuration to use

Modified: gnunet/src/fs/gnunet-service-fs_drq.c
===================================================================
--- gnunet/src/fs/gnunet-service-fs_drq.c       2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/fs/gnunet-service-fs_drq.c       2010-02-18 15:07:02 UTC (rev 
10372)
@@ -300,6 +300,15 @@
  * 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,

Modified: gnunet/src/include/gnunet_container_lib.h
===================================================================
--- gnunet/src/include/gnunet_container_lib.h   2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/include/gnunet_container_lib.h   2010-02-18 15:07:02 UTC (rev 
10372)
@@ -243,7 +243,7 @@
  *
  * @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

Modified: gnunet/src/include/gnunet_core_service.h
===================================================================
--- gnunet/src/include/gnunet_core_service.h    2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/include/gnunet_core_service.h    2010-02-18 15:07:02 UTC (rev 
10372)
@@ -240,6 +240,7 @@
  * @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

Modified: gnunet/src/include/gnunet_disk_lib.h
===================================================================
--- gnunet/src/include/gnunet_disk_lib.h        2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/include/gnunet_disk_lib.h        2010-02-18 15:07:02 UTC (rev 
10372)
@@ -340,9 +340,11 @@
  *
  * @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 @@
 
 /**
  * Get the handle to a particular pipe end
+ *
  * @param p pipe
  * @param n end to access
  * @return handle for the respective end

Modified: gnunet/src/include/gnunet_os_lib.h
===================================================================
--- gnunet/src/include/gnunet_os_lib.h  2010-02-18 14:33:35 UTC (rev 10371)
+++ gnunet/src/include/gnunet_os_lib.h  2010-02-18 15:07:02 UTC (rev 10372)
@@ -196,7 +196,9 @@
  * @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, ...);
 
 
 /**

Modified: gnunet/src/transport/gnunet-nat-client-udp.c
===================================================================
--- gnunet/src/transport/gnunet-nat-client-udp.c        2010-02-18 14:33:35 UTC 
(rev 10371)
+++ gnunet/src/transport/gnunet-nat-client-udp.c        2010-02-18 15:07:02 UTC 
(rev 10372)
@@ -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
  */

Modified: gnunet/src/transport/gnunet-nat-server-udp.c
===================================================================
--- gnunet/src/transport/gnunet-nat-server-udp.c        2010-02-18 14:33:35 UTC 
(rev 10371)
+++ gnunet/src/transport/gnunet-nat-server-udp.c        2010-02-18 15:07:02 UTC 
(rev 10372)
@@ -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
  */

Modified: gnunet/src/transport/gnunet-service-transport.c
===================================================================
--- gnunet/src/transport/gnunet-service-transport.c     2010-02-18 14:33:35 UTC 
(rev 10371)
+++ gnunet/src/transport/gnunet-service-transport.c     2010-02-18 15:07:02 UTC 
(rev 10372)
@@ -1844,11 +1844,11 @@
  * (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 @@
  *
  * @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

Modified: gnunet/src/transport/gnunet-service-transport_blacklist.c
===================================================================
--- gnunet/src/transport/gnunet-service-transport_blacklist.c   2010-02-18 
14:33:35 UTC (rev 10371)
+++ gnunet/src/transport/gnunet-service-transport_blacklist.c   2010-02-18 
15:07:02 UTC (rev 10372)
@@ -250,6 +250,7 @@
 /**
  * Initialize the blacklisting subsystem.
  *
+ * @param server server of the transport service
  * @param s scheduler to use
  */
 void 

Modified: gnunet/src/transport/plugin_transport.h
===================================================================
--- gnunet/src/transport/plugin_transport.h     2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/transport/plugin_transport.h     2010-02-18 15:07:02 UTC (rev 
10372)
@@ -171,7 +171,8 @@
  *
  * @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

Modified: gnunet/src/transport/plugin_transport_tcp.c
===================================================================
--- gnunet/src/transport/plugin_transport_tcp.c 2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/transport/plugin_transport_tcp.c 2010-02-18 15:07:02 UTC (rev 
10372)
@@ -557,6 +557,7 @@
  * @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

Modified: gnunet/src/transport/plugin_transport_template.c
===================================================================
--- gnunet/src/transport/plugin_transport_template.c    2010-02-18 14:33:35 UTC 
(rev 10371)
+++ gnunet/src/transport/plugin_transport_template.c    2010-02-18 15:07:02 UTC 
(rev 10372)
@@ -136,13 +136,23 @@
  * @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,

Modified: gnunet/src/transport/plugin_transport_udp.c
===================================================================
--- gnunet/src/transport/plugin_transport_udp.c 2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/transport/plugin_transport_udp.c 2010-02-18 15:07:02 UTC (rev 
10372)
@@ -75,8 +75,6 @@
 
 };
 
-/* Forward definition */
-struct Plugin;
 
 struct PrettyPrinterContext
 {
@@ -111,6 +109,11 @@
   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 @@
    */
   uint16_t adv_port;
 
-  /*
-   * FD Read set
-   */
-  struct GNUNET_NETWORK_FDSet *rs;
-
 };
 
 /* *********** globals ************* */
@@ -148,13 +146,14 @@
 /**
  * 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 @@
  * @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

Modified: gnunet/src/transport/transport_api.c
===================================================================
--- gnunet/src/transport/transport_api.c        2010-02-18 14:33:35 UTC (rev 
10371)
+++ gnunet/src/transport/transport_api.c        2010-02-18 15:07:02 UTC (rev 
10372)
@@ -897,7 +897,6 @@
  * 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 @@
 /**
  * Free neighbour. 
  * 
- * @param h our state
  * @param n the entry to free
  */
 static void

Modified: gnunet/src/util/disk.c
===================================================================
--- gnunet/src/util/disk.c      2010-02-18 14:33:35 UTC (rev 10371)
+++ gnunet/src/util/disk.c      2010-02-18 15:07:02 UTC (rev 10372)
@@ -1675,10 +1675,12 @@
  * 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 @@
 
 /**
  * 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,

Modified: gnunet/src/util/os_priority.c
===================================================================
--- gnunet/src/util/os_priority.c       2010-02-18 14:33:35 UTC (rev 10371)
+++ gnunet/src/util/os_priority.c       2010-02-18 15:07:02 UTC (rev 10372)
@@ -119,12 +119,16 @@
 /**
  * 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;