From d0efe84c15166730f5ee3f7af74ca428ae37f7ff Mon Sep 17 00:00:00 2001
From: Christian Grothoff <christian@grothoff.org>
Date: Fri, 11 Sep 2009 11:26:42 +0000
Subject: [PATCH] fixing docu issues

---
 src/arm/arm_api.c                         | 35 +++++++++++++++++++++++
 src/datacache/datacache.c                 |  2 +-
 src/datacache/plugin_datacache.h          |  5 +++-
 src/datacache/plugin_datacache_sqlite.c   | 10 +++++++
 src/datacache/plugin_datacache_template.c | 10 +++++++
 src/datastore/datastore_api.c             |  2 ++
 src/datastore/gnunet-service-datastore.c  |  4 ++-
 src/fs/gnunet-service-fs.c                |  2 +-
 src/include/gnunet_fs_service.h           |  4 ++-
 src/include/gnunet_getopt_lib.h           |  2 +-
 src/include/winproc.h                     |  4 +--
 src/transport/gnunet-transport.c          |  2 +-
 src/transport/plugin_transport_http.c     |  2 +-
 src/transport/plugin_transport_smtp.c     |  2 +-
 src/transport/plugin_transport_udp.c      |  2 +-
 src/upnp/upnp_init.c                      |  2 +-
 src/upnp/upnp_ip.c                        |  2 +-
 src/upnp/upnp_ip.h                        |  2 +-
 src/upnp/upnp_util.h                      |  2 +-
 src/upnp/upnp_xmlnode.c                   |  2 +-
 src/upnp/upnp_xmlnode.h                   |  2 +-
 src/util/common_allocation.c              |  2 +-
 src/util/network.c                        |  4 +--
 src/util/os_load.c                        |  4 +--
 src/util/os_priority.c                    |  2 +-
 src/util/scheduler.c                      |  2 +-
 src/util/win.cc                           |  4 +--
 src/util/winproc.c                        |  2 +-
 28 files changed, 92 insertions(+), 28 deletions(-)

diff --git a/src/arm/arm_api.c b/src/arm/arm_api.c
index 7ae3e9513..e5071c4dc 100644
--- a/src/arm/arm_api.c
+++ b/src/arm/arm_api.c
@@ -33,18 +33,52 @@
 #include "arm.h"
 
 
+/**
+ * FIXME: document.
+ */
 struct ArmContext
 {
+
+  /**
+   * FIXME: document.
+   */
   GNUNET_ARM_Callback callback;
+
+  /**
+   * FIXME: document.
+   */
   void *cls;
+
+  /**
+   * FIXME: document.
+   */
   char *service_name;
+
+  /**
+   * FIXME: document.
+   */
   struct GNUNET_CLIENT_Connection *client;
+
+  /**
+   * FIXME: document.
+   */
   const struct GNUNET_CONFIGURATION_Handle *cfg;
+
+  /**
+   * FIXME: document.
+   */
   struct GNUNET_TIME_Absolute timeout;
+
+  /**
+   * FIXME: document.
+   */
   uint16_t type;
 };
 
 
+/**
+ * FIXME: document.
+ */
 static void
 arm_service_report (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
 {
@@ -192,6 +226,7 @@ send_service_msg (void *cls, size_t size, void *buf)
  * @param timeout how long to wait before failing for good
  * @param cb callback to invoke when service is ready
  * @param cb_cls closure for callback
+ * @param type type of the request 
  */
 static void
 change_service (const char *service_name,
diff --git a/src/datacache/datacache.c b/src/datacache/datacache.c
index 3b233d16d..afdfb0c4c 100644
--- a/src/datacache/datacache.c
+++ b/src/datacache/datacache.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file datacache/datacache_api.c
+ * @file datacache/datacache.c
  * @brief datacache API implementation
  * @author Christian Grothoff
  */
diff --git a/src/datacache/plugin_datacache.h b/src/datacache/plugin_datacache.h
index 39119339d..d3768cf44 100644
--- a/src/datacache/plugin_datacache.h
+++ b/src/datacache/plugin_datacache.h
@@ -105,7 +105,7 @@ struct GNUNET_DATACACHE_PluginFunctions {
   /**
    * Store an item in the datastore.
    *
-   * @param key key to store data under
+   * @param cls closure (internal context for the plugin)
    * @param size number of bytes in data
    * @param data data to store
    * @param type type of the value
@@ -124,9 +124,11 @@ struct GNUNET_DATACACHE_PluginFunctions {
    * Iterate over the results for a particular key
    * in the datastore.
    *
+   * @param cls closure (internal context for the plugin)
    * @param key
    * @param type entries of which type are relevant?
    * @param iter maybe NULL (to just count)
+   * @param iter_cls closure for iter
    * @return the number of results found
    */
   unsigned int (*get) (void *cls,
@@ -140,6 +142,7 @@ struct GNUNET_DATACACHE_PluginFunctions {
    * Delete the entry with the lowest expiration value
    * from the datacache right now.
    * 
+   * @param cls closure (internal context for the plugin)
    * @return GNUNET_OK on success, GNUNET_SYSERR on error
    */ 
   int (*del) (void *cls);
diff --git a/src/datacache/plugin_datacache_sqlite.c b/src/datacache/plugin_datacache_sqlite.c
index e8ef5cd09..7595211c1 100644
--- a/src/datacache/plugin_datacache_sqlite.c
+++ b/src/datacache/plugin_datacache_sqlite.c
@@ -86,6 +86,7 @@ sq_prepare (sqlite3 * dbh, const char *zSql,    /* SQL statement, UTF-8 encoded
 /**
  * Store an item in the datastore.
  *
+ * @param cls closure (our "struct Plugin")
  * @param key key to store data under
  * @param size number of bytes in data
  * @param data data to store
@@ -155,9 +156,11 @@ sqlite_plugin_put (void *cls,
  * Iterate over the results for a particular key
  * in the datastore.
  *
+ * @param cls closure (our "struct Plugin")
  * @param key
  * @param type entries of which type are relevant?
  * @param iter maybe NULL (to just count)
+ * @param iter_cls closure for iter
  * @return the number of results found
  */
 static unsigned int 
@@ -259,6 +262,7 @@ sqlite_plugin_get (void *cls,
  * Delete the entry with the lowest expiration value
  * from the datacache right now.
  * 
+ * @param cls closure (our "struct Plugin")
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */ 
 static int 
@@ -337,6 +341,9 @@ sqlite_plugin_del (void *cls)
 
 /**
  * Entry point for the plugin.
+ *
+ * @param cls closure (the "struct GNUNET_DATACACHE_PluginEnvironmnet")
+ * @return the plugin's closure (our "struct Plugin")
  */
 void *
 libgnunet_plugin_datacache_sqlite_init (void *cls)
@@ -398,6 +405,9 @@ libgnunet_plugin_datacache_sqlite_init (void *cls)
 
 /**
  * Exit point from the plugin.
+ *
+ * @param cls closure (our "struct Plugin")
+ * @return NULL
  */
 void *
 libgnunet_plugin_datacache_sqlite_done (void *cls)
diff --git a/src/datacache/plugin_datacache_template.c b/src/datacache/plugin_datacache_template.c
index 501284c30..163f72a7a 100644
--- a/src/datacache/plugin_datacache_template.c
+++ b/src/datacache/plugin_datacache_template.c
@@ -43,6 +43,7 @@ struct Plugin
 /**
  * Store an item in the datastore.
  *
+ * @param cls closure (our "struct Plugin")
  * @param key key to store data under
  * @param size number of bytes in data
  * @param data data to store
@@ -67,9 +68,11 @@ template_plugin_put (void *cls,
  * Iterate over the results for a particular key
  * in the datastore.
  *
+ * @param cls closure (our "struct Plugin")
  * @param key
  * @param type entries of which type are relevant?
  * @param iter maybe NULL (to just count)
+ * @param iter_cls closure for iter
  * @return the number of results found
  */
 static unsigned int 
@@ -88,6 +91,7 @@ template_plugin_get (void *cls,
  * Delete the entry with the lowest expiration value
  * from the datacache right now.
  * 
+ * @param cls closure (our "struct Plugin")
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */ 
 static int 
@@ -100,6 +104,9 @@ template_plugin_del (void *cls)
 
 /**
  * Entry point for the plugin.
+ *
+ * @param cls closure (the "struct GNUNET_DATACACHE_PluginEnvironmnet")
+ * @return the plugin's closure (our "struct Plugin")
  */
 void *
 libgnunet_plugin_datacache_template_init (void *cls)
@@ -123,6 +130,9 @@ libgnunet_plugin_datacache_template_init (void *cls)
 
 /**
  * Exit point from the plugin.
+ *
+ * @param cls closure (our "struct Plugin")
+ * @return NULL
  */
 void *
 libgnunet_plugin_datacache_template_done (void *cls)
diff --git a/src/datastore/datastore_api.c b/src/datastore/datastore_api.c
index 929698a5b..7b674087e 100644
--- a/src/datastore/datastore_api.c
+++ b/src/datastore/datastore_api.c
@@ -335,6 +335,8 @@ transmit_for_status (struct GNUNET_DATASTORE_Handle *h,
  * lower anonymity level is used.
  *
  * @param h handle to the datastore
+ * @param rid reservation ID to use (from "reserve"); use 0 if no
+ *            prior reservation was made
  * @param key key for the value
  * @param size number of bytes in data
  * @param data content stored
diff --git a/src/datastore/gnunet-service-datastore.c b/src/datastore/gnunet-service-datastore.c
index 900c1a8c8..f139998e9 100644
--- a/src/datastore/gnunet-service-datastore.c
+++ b/src/datastore/gnunet-service-datastore.c
@@ -456,6 +456,8 @@ transmit_callback (void *cls,
  *
  * @param client target of the message
  * @param msg message to transmit, will be freed!
+ * @param tc function to call afterwards
+ * @param tc_cls closure for tc
  * @param end is this the last response (and we should
  *        signal the server completion accodingly after
  *        transmitting this message)?
@@ -537,7 +539,7 @@ transmit_status (struct GNUNET_SERVER_Client *client,
  * Function called once the transmit operation has
  * either failed or succeeded.
  *
- * @param cls closure
+ * @param next_cls closure for calling "next_request" callback
  * @param status GNUNET_OK on success, GNUNET_SYSERR on error
  */
 static void 
diff --git a/src/fs/gnunet-service-fs.c b/src/fs/gnunet-service-fs.c
index 18cb69d68..2fad754c0 100644
--- a/src/fs/gnunet-service-fs.c
+++ b/src/fs/gnunet-service-fs.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file statistics/gnunet-service-fs.c
+ * @file fs/gnunet-service-fs.c
  * @brief program that provides the file-sharing service
  * @author Christian Grothoff
  */
diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h
index 108c0c68f..f89a343b9 100644
--- a/src/include/gnunet_fs_service.h
+++ b/src/include/gnunet_fs_service.h
@@ -382,7 +382,9 @@ GNUNET_FS_uri_test_loc (const struct GNUNET_FS_Uri *uri);
  * Construct a keyword-URI from meta-data (take all entries
  * in the meta-data and construct one large keyword URI
  * that lists all keywords that can be found in the meta-data).
- * @deprecated
+ *
+ * @param md metadata to use
+ * @return NULL on error, otherwise a KSK URI
  */
 struct GNUNET_FS_Uri *
 GNUNET_FS_uri_ksk_create_from_meta_data (const struct GNUNET_CONTAINER_MetaData *md);
diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index e7063d3d0..35db3f6d1 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -99,7 +99,7 @@ struct GNUNET_GETOPT_CommandLineOption
 {
 
   /**
-   * Short name of the option (use '\0' for none).
+   * Short name of the option (use '\\0' for none).
    */
   const char shortName;
 
diff --git a/src/include/winproc.h b/src/include/winproc.h
index 9619f60d9..a42418141 100644
--- a/src/include/winproc.h
+++ b/src/include/winproc.h
@@ -19,10 +19,10 @@
 */
 
 /**
- * @file util/winproc.h
+ * @file include/winproc.h
  * @brief Definitions for MS Windows
  * @author Nils Durner
- **/
+ */
 
 #ifndef _WINPROC_H
 #define _WINPROC_H
diff --git a/src/transport/gnunet-transport.c b/src/transport/gnunet-transport.c
index 52475e3eb..17f6e6f78 100644
--- a/src/transport/gnunet-transport.c
+++ b/src/transport/gnunet-transport.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file server/gnunet-transport.c
+ * @file src/transport/gnunet-transport.c
  * @brief Tool to help configure the transports.
  * @author Christian Grothoff
  *
diff --git a/src/transport/plugin_transport_http.c b/src/transport/plugin_transport_http.c
index 78691852d..c2f531b54 100644
--- a/src/transport/plugin_transport_http.c
+++ b/src/transport/plugin_transport_http.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file transports/http.c
+ * @file transport/plugin_transport_http.c
  * @brief Implementation of the HTTP transport service
  * @author Christian Grothoff
  */
diff --git a/src/transport/plugin_transport_smtp.c b/src/transport/plugin_transport_smtp.c
index f7cc530e4..b93b16fb7 100644
--- a/src/transport/plugin_transport_smtp.c
+++ b/src/transport/plugin_transport_smtp.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file transports/smtp.c
+ * @file transport/plugin_transport_smtp.c
  * @brief Implementation of the SMTP transport service
  * @author Christian Grothoff
  * @author Renaldo Ferreira
diff --git a/src/transport/plugin_transport_udp.c b/src/transport/plugin_transport_udp.c
index ce8a2f89c..840025997 100644
--- a/src/transport/plugin_transport_udp.c
+++ b/src/transport/plugin_transport_udp.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file transports/udp.c
+ * @file transport/plugin_transport_udp.c
  * @brief Implementation of the UDP transport service
  * @author Christian Grothoff
  */
diff --git a/src/upnp/upnp_init.c b/src/upnp/upnp_init.c
index b0eb77c32..19167342b 100644
--- a/src/upnp/upnp_init.c
+++ b/src/upnp/upnp_init.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file src/transports/upnp/init.c
+ * @file transport/upnp_init.c
  * @brief API for UPnP access
  * @author Christian Grothoff
  */
diff --git a/src/upnp/upnp_ip.c b/src/upnp/upnp_ip.c
index 3716fc671..cb102cba5 100644
--- a/src/upnp/upnp_ip.c
+++ b/src/upnp/upnp_ip.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file transports/upnp/ip.c
+ * @file transport/upnp_ip.c
  * @brief code to determine the IP of the local machine
  *
  * @author Christian Grothoff
diff --git a/src/upnp/upnp_ip.h b/src/upnp/upnp_ip.h
index adc06bbd5..62cb05f5e 100644
--- a/src/upnp/upnp_ip.h
+++ b/src/upnp/upnp_ip.h
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file transports/upnp/ip.h
+ * @file transport/upnp_ip.h
  * @brief
  *
  * @author Christian Grothoff
diff --git a/src/upnp/upnp_util.h b/src/upnp/upnp_util.h
index 89a8d71cf..32c790493 100644
--- a/src/upnp/upnp_util.h
+++ b/src/upnp/upnp_util.h
@@ -1,5 +1,5 @@
 /**
- * @file util.h Utility Functions
+ * @file transport/upnp_util.h Utility Functions
  * @ingroup core
  *
  * gaim
diff --git a/src/upnp/upnp_xmlnode.c b/src/upnp/upnp_xmlnode.c
index b37528f00..aeea157e1 100644
--- a/src/upnp/upnp_xmlnode.c
+++ b/src/upnp/upnp_xmlnode.c
@@ -1,5 +1,5 @@
 /**
- * @file xmlnode.c XML DOM functions
+ * @file transport/upnp_xmlnode.c XML DOM functions
  *
  * gaim
  *
diff --git a/src/upnp/upnp_xmlnode.h b/src/upnp/upnp_xmlnode.h
index 199975e37..191ef14d2 100644
--- a/src/upnp/upnp_xmlnode.h
+++ b/src/upnp/upnp_xmlnode.h
@@ -1,5 +1,5 @@
 /**
- * @file xmlnode.h XML DOM functions
+ * @file transport/upnp_xmlnode.h XML DOM functions
  * @ingroup core
  *
  * gaim
diff --git a/src/util/common_allocation.c b/src/util/common_allocation.c
index 71ebb0905..7a79eef6d 100644
--- a/src/util/common_allocation.c
+++ b/src/util/common_allocation.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file util/memory/common_allocation.c
+ * @file util/common_allocation.c
  * @brief wrapper around malloc/free
  * @author Christian Grothoff
  */
diff --git a/src/util/network.c b/src/util/network.c
index 7e4743a10..e112d9093 100644
--- a/src/util/network.c
+++ b/src/util/network.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file util/sock.c
+ * @file util/network.c
  * @brief basic, low-level networking interface
  * @author Nils Durner
  */
@@ -821,4 +821,4 @@ GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds,
 #endif
 }
 
-/* end of network_socket.c */
+/* end of network.c */
diff --git a/src/util/os_load.c b/src/util/os_load.c
index 21e74eb49..a5a197ebe 100644
--- a/src/util/os_load.c
+++ b/src/util/os_load.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file util/os_load_cpu.c
+ * @file util/os_load.c
  * @brief calls to determine current CPU load
  * @author Tzvetan Horozov
  * @author Christian Grothoff
@@ -650,4 +650,4 @@ void __attribute__ ((destructor)) GNUNET_cpustats_ltdl_fini ()
 }
 
 
-/* end of os_load_cpu.c */
+/* end of os_load.c */
diff --git a/src/util/os_priority.c b/src/util/os_priority.c
index 4e820b8d5..46e2deb5c 100644
--- a/src/util/os_priority.c
+++ b/src/util/os_priority.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file util/os/priority.c
+ * @file util/os_priority.c
  * @brief Methods to set process priority
  * @author Nils Durner
  */
diff --git a/src/util/scheduler.c b/src/util/scheduler.c
index d1d4e1970..12b7c4cf2 100644
--- a/src/util/scheduler.c
+++ b/src/util/scheduler.c
@@ -19,7 +19,7 @@
  */
 
 /**
- * @file util/scheduler/scheduler.c
+ * @file util/scheduler.c
  * @brief schedule computations using continuation passing style
  * @author Christian Grothoff
  */
diff --git a/src/util/win.cc b/src/util/win.cc
index 8e71744d0..8a168d238 100644
--- a/src/util/win.cc
+++ b/src/util/win.cc
@@ -19,10 +19,10 @@
 */
 
 /**
- * @file util/win/win.cc
+ * @file util/win.cc
  * @brief Helper functions for MS Windows in C++
  * @author Nils Durner
- **/
+ */
 
 #ifndef _WIN_CC
 #define _WIN_CC
diff --git a/src/util/winproc.c b/src/util/winproc.c
index 469e1fb41..862222c05 100644
--- a/src/util/winproc.c
+++ b/src/util/winproc.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file util/win/winproc.c
+ * @file util/winproc.c
  * @brief Functions for MS Windows
  * @author Nils Durner
  */
-- 
2.25.1