[GNUnet-SVN] r9128 - in gnunet/src: include util

[gnunet]

Author: grothoff
Date: 2009-10-07 05:10:42 -0600 (Wed, 07 Oct 2009)
New Revision: 9128

Modified:
   gnunet/src/include/gnunet_container_lib.h
   gnunet/src/include/gnunet_disk_lib.h
   gnunet/src/util/common_logging.c
   gnunet/src/util/configuration.c
   gnunet/src/util/connection.c
   gnunet/src/util/container_bloomfilter.c
   gnunet/src/util/container_meta_data.c
   gnunet/src/util/container_slist.c
   gnunet/src/util/disk.c
   gnunet/src/util/network.c
Log:
improving documentation

Modified: gnunet/src/include/gnunet_container_lib.h
===================================================================
--- gnunet/src/include/gnunet_container_lib.h   2009-10-06 11:58:00 UTC (rev 
9127)
+++ gnunet/src/include/gnunet_container_lib.h   2009-10-07 11:10:42 UTC (rev 
9128)
@@ -372,6 +372,7 @@
  * Serialize meta-data to target.
  *
  * @param md metadata to serialize
+ * @param target where to write the serialized metadata
  * @param size maximum number of bytes available
  * @param opt is it ok to just write SOME of the
  *        meta-data to match the size constraint,
@@ -388,9 +389,11 @@
                                           
GNUNET_CONTAINER_MetaDataSerializationOptions
                                           opt);
 
+
 /**
- * Compute size of the meta-data in
- * serialized form.
+ * Estimate (!) the size of the meta-data in
+ * serialized form.  The estimate MAY be higher
+ * than what is strictly needed.
  *
  * @param md metadata to inspect
  * @param opt is it ok to just write SOME of the

Modified: gnunet/src/include/gnunet_disk_lib.h
===================================================================
--- gnunet/src/include/gnunet_disk_lib.h        2009-10-06 11:58:00 UTC (rev 
9127)
+++ gnunet/src/include/gnunet_disk_lib.h        2009-10-07 11:10:42 UTC (rev 
9128)
@@ -548,8 +548,8 @@
 /**
  * Unlock a part of a file
  * @param fh file handle
- * @param lockStart absolute position from where to unlock
- * @param lockEnd absolute position until where to unlock
+ * @param unlockStart absolute position from where to unlock
+ * @param unlockEnd absolute position until where to unlock
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
@@ -582,7 +582,7 @@
  *
  * @param cfg configuration to use
  * @param serviceName name of the service asking
- * @param varargs is NULL-terminated list of
+ * @param ... is NULL-terminated list of
  *                path components to append to the
  *                private directory name.
  * @return the constructed filename

Modified: gnunet/src/util/common_logging.c
===================================================================
--- gnunet/src/util/common_logging.c    2009-10-06 11:58:00 UTC (rev 9127)
+++ gnunet/src/util/common_logging.c    2009-10-07 11:10:42 UTC (rev 9128)
@@ -254,7 +254,7 @@
 /**
  * Flush an existing bulk report to the output.
  *
- * @param datastr our current timestamp
+ * @param datestr our current timestamp
  */
 static void
 flush_bulk (const char *datestr)

Modified: gnunet/src/util/configuration.c
===================================================================
--- gnunet/src/util/configuration.c     2009-10-06 11:58:00 UTC (rev 9127)
+++ gnunet/src/util/configuration.c     2009-10-07 11:10:42 UTC (rev 9128)
@@ -278,7 +278,7 @@
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
-GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *data,
+GNUNET_CONFIGURATION_write (struct GNUNET_CONFIGURATION_Handle *cfg,
                             const char *filename)
 {
   struct ConfigSection *sec;
@@ -299,7 +299,7 @@
     }
   GNUNET_free (fn);
   error = 0;
-  sec = data->sections;
+  sec = cfg->sections;
   while (sec != NULL)
     {
       if (0 > fprintf (fp, "[%s]\n", sec->name))
@@ -344,10 +344,10 @@
   GNUNET_assert (0 == fclose (fp));
   if (error != 0)
     {
-      data->dirty = GNUNET_SYSERR;      /* last write failed */
+      cfg->dirty = GNUNET_SYSERR;      /* last write failed */
       return GNUNET_SYSERR;
     }
-  data->dirty = GNUNET_NO;      /* last write succeeded */
+  cfg->dirty = GNUNET_NO;      /* last write succeeded */
   return GNUNET_OK;
 }
 
@@ -381,12 +381,13 @@
 
 
 /**
- * FIXME.
+ * Copy a configuration value to the given target configuration.
+ * Overwrites existing entries.
  *
  * @param cls the destination configuration (struct 
GNUNET_CONFIGURATION_Handle*)
- * @param section FIXME
- * @param option FIXME
- * @param value FIXME
+ * @param section section for the value
+ * @param option option name of the value
+ * @param value value to copy 
  */
 static void
 copy_entry (void *cls,
@@ -402,7 +403,7 @@
 /**
  * Duplicate an existing configuration object.
  *
- * @param c configuration to duplicate
+ * @param cfg configuration to duplicate
  * @return duplicate configuration
  */
 struct GNUNET_CONFIGURATION_Handle *
@@ -419,16 +420,16 @@
 /**
  * FIXME.
  *
- * @param data FIXME
+ * @param cfg FIXME
  * @param section FIXME
  * @return matching entry, NULL if not found
  */
 static struct ConfigSection *
-findSection (const struct GNUNET_CONFIGURATION_Handle *data, const char 
*section)
+findSection (const struct GNUNET_CONFIGURATION_Handle *cfg, const char 
*section)
 {
   struct ConfigSection *pos;
 
-  pos = data->sections;
+  pos = cfg->sections;
   while ((pos != NULL) && (0 != strcasecmp (section, pos->name)))
     pos = pos->next;
   return pos;
@@ -438,19 +439,19 @@
 /**
  * FIXME.
  *
- * @param data FIXME
+ * @param cfg FIXME
  * @param section FIXME
  * @param key FIXME
  * @return matching entry, NULL if not found
  */
 static struct ConfigEntry *
-findEntry (const struct GNUNET_CONFIGURATION_Handle *data,
+findEntry (const struct GNUNET_CONFIGURATION_Handle *cfg,
            const char *section, const char *key)
 {
   struct ConfigSection *sec;
   struct ConfigEntry *pos;
 
-  sec = findSection (data, section);
+  sec = findSection (cfg, section);
   if (sec == NULL)
     return NULL;
   pos = sec->entries;
@@ -470,27 +471,27 @@
  */
 void
 GNUNET_CONFIGURATION_set_value_string (struct GNUNET_CONFIGURATION_Handle
-                                       *data,
+                                       *cfg,
                                        const char *section,
                                        const char *option, const char *value)
 {
   struct ConfigSection *sec;
   struct ConfigEntry *e;
 
-  e = findEntry (data, section, option);
+  e = findEntry (cfg, section, option);
   if (e != NULL)
     {
       GNUNET_free_non_null (e->val);
       e->val = GNUNET_strdup (value);
       return;
     }
-  sec = findSection (data, section);
+  sec = findSection (cfg, section);
   if (sec == NULL)
     {
       sec = GNUNET_malloc (sizeof (struct ConfigSection));
       sec->name = GNUNET_strdup (section);
-      sec->next = data->sections;
-      data->sections = sec;
+      sec->next = cfg->sections;
+      cfg->sections = sec;
     }
   e = GNUNET_malloc (sizeof (struct ConfigEntry));
   e->key = GNUNET_strdup (option);
@@ -671,7 +672,7 @@
  * "FOO" is set to "DIRECTORY".
  *
  * @param cfg configuration to use for path expansion
- * @param old string to $-expand (will be freed!)
+ * @param orig string to $-expand (will be freed!)
  * @return $-expanded string
  */
 char *
@@ -733,19 +734,19 @@
  */
 int
 GNUNET_CONFIGURATION_get_value_filename (const struct 
GNUNET_CONFIGURATION_Handle
-                                         *data, const char *section,
+                                         *cfg, const char *section,
                                          const char *option, char **value)
 {
   int ret;
   char *tmp;
 
   tmp = NULL;
-  ret = GNUNET_CONFIGURATION_get_value_string (data, section, option, &tmp);
+  ret = GNUNET_CONFIGURATION_get_value_string (cfg, section, option, &tmp);
   if (ret == GNUNET_SYSERR)
     return ret;
   if (tmp != NULL)
     {
-      tmp = GNUNET_CONFIGURATION_expand_dollar (data, tmp);
+      tmp = GNUNET_CONFIGURATION_expand_dollar (cfg, tmp);
       *value = GNUNET_STRINGS_filename_expand (tmp);
       GNUNET_free (tmp);
       if (*value == NULL)
@@ -1054,7 +1055,7 @@
  */
 int
 GNUNET_CONFIGURATION_load (struct GNUNET_CONFIGURATION_Handle *cfg,
-                           const char *cfgfn)
+                           const char *filename)
 {
   char *baseconfig;
   char *ipath;
@@ -1068,8 +1069,8 @@
   GNUNET_free (ipath);
   if ((GNUNET_OK !=
        GNUNET_CONFIGURATION_parse (cfg, baseconfig)) ||
-      (!((cfgfn == NULL) ||
-         (GNUNET_OK == GNUNET_CONFIGURATION_parse (cfg, cfgfn)))))
+      (!((filename == NULL) ||
+         (GNUNET_OK == GNUNET_CONFIGURATION_parse (cfg, filename)))))
     {
       GNUNET_free (baseconfig);
       return GNUNET_SYSERR;

Modified: gnunet/src/util/connection.c
===================================================================
--- gnunet/src/util/connection.c        2009-10-06 11:58:00 UTC (rev 9127)
+++ gnunet/src/util/connection.c        2009-10-07 11:10:42 UTC (rev 9128)
@@ -692,7 +692,7 @@
  * Scheduler let us know that we're either ready to write on the
  * socket OR connect timed out.  Do the right thing.
  *
- * @param ap the address we were probing
+ * @param cls the "struct AddressProbe*" with the address that we are probing
  * @param tc success or failure info about the connect attempt.
  */
 static void
@@ -1188,7 +1188,6 @@
  * receive call per socket at any given point in time (so do not
  * call receive again until the receiver callback has been invoked).
  *
- * @param sched scheduler to use
  * @param sock socket handle
  * @param max maximum number of bytes to read
  * @param timeout maximum amount of time to wait (use -1 for "forever")

Modified: gnunet/src/util/container_bloomfilter.c
===================================================================
--- gnunet/src/util/container_bloomfilter.c     2009-10-06 11:58:00 UTC (rev 
9127)
+++ gnunet/src/util/container_bloomfilter.c     2009-10-07 11:10:42 UTC (rev 
9128)
@@ -520,6 +520,7 @@
  * Copy the raw data of this bloomfilter into
  * the given data array.
  *
+ * @param bf bloomfilter to take the raw data from
  * @param data where to write the data
  * @param size the size of the given data array
  * @return GNUNET_SYSERR if the data array is not big enough

Modified: gnunet/src/util/container_meta_data.c
===================================================================
--- gnunet/src/util/container_meta_data.c       2009-10-06 11:58:00 UTC (rev 
9127)
+++ gnunet/src/util/container_meta_data.c       2009-10-07 11:10:42 UTC (rev 
9128)
@@ -247,6 +247,7 @@
 /**
  * Get a thumbnail from the meta-data (if present).
  *
+ * @param md metadata to get the thumbnail from
  * @param thumb will be set to the thumbnail data.  Must be
  *        freed by the caller!
  * @return number of bytes in thumbnail, 0 if not available
@@ -333,6 +334,7 @@
   return ret;
 }
 
+
 static unsigned int
 tryCompression (char *data, unsigned int oldSize)
 {
@@ -434,7 +436,9 @@
 /**
  * Serialize meta-data to target.
  *
- * @param size maximum number of bytes available
+ * @param md metadata to serialize
+ * @param target where to write the serialized metadata
+ * @param max maximum number of bytes available in target
  * @param part is it ok to just write SOME of the
  *        meta-data to match the size constraint,
  *        possibly discarding some data?
@@ -532,13 +536,19 @@
  * Estimate (!) the size of the meta-data in
  * serialized form.  The estimate MAY be higher
  * than what is strictly needed.
+ *
+ * @param md metadata to inspect
+ * @param opt is it ok to just write SOME of the
+ *        meta-data to match the size constraint,
+ *        possibly discarding some data?
+ * @return number of bytes needed for serialization, -1 on error
  */
 ssize_t
 GNUNET_CONTAINER_meta_data_get_serialized_size (const struct
                                                 GNUNET_CONTAINER_MetaData *md,
                                                 enum
                                                 
GNUNET_CONTAINER_MetaDataSerializationOptions
-                                                part)
+                                                opt)
 {
   struct MetaDataHeader *hdr;
   size_t size;
@@ -567,7 +577,7 @@
       memcpy (&((char *) hdr)[pos], md->items[i].data, len);
       pos += len;
     }
-  if ((part & GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS) == 0)
+  if ((opt & GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS) == 0)
     {
       pos =
         tryCompression ((char *) &hdr[1],
@@ -583,9 +593,12 @@
   return size;
 }
 
+
 /**
  * Deserialize meta-data.  Initializes md.
- * @param size number of bytes available
+ *
+ * @param input buffer with the serialized metadata
+ * @param size number of bytes available in input
  * @return MD on success, NULL on error (i.e.
  *         bad format)
  */

Modified: gnunet/src/util/container_slist.c
===================================================================
--- gnunet/src/util/container_slist.c   2009-10-06 11:58:00 UTC (rev 9127)
+++ gnunet/src/util/container_slist.c   2009-10-07 11:10:42 UTC (rev 9128)
@@ -215,7 +215,7 @@
  *
  * @param l list
  * @param buf payload buffer to find
- * @param lenght of the payload
+ * @param len length of the payload (number of bytes in buf)
  */
 int
 GNUNET_CONTAINER_slist_contains (const struct GNUNET_CONTAINER_SList *l,

Modified: gnunet/src/util/disk.c
===================================================================
--- gnunet/src/util/disk.c      2009-10-06 11:58:00 UTC (rev 9127)
+++ gnunet/src/util/disk.c      2009-10-07 11:10:42 UTC (rev 9128)
@@ -536,20 +536,20 @@
  * Create the directory structure for storing
  * a file.
  *
- * @param dir name of a file in the directory
+ * @param filename name of a file in the directory
  * @returns GNUNET_OK on success,
  *          GNUNET_SYSERR on failure,
  *          GNUNET_NO if the directory
  *          exists but is not writeable for us
  */
 int
-GNUNET_DISK_directory_create_for_file (const char *dir)
+GNUNET_DISK_directory_create_for_file (const char *filename)
 {
   char *rdir;
   int len;
   int ret;
 
-  rdir = GNUNET_STRINGS_filename_expand (dir);
+  rdir = GNUNET_STRINGS_filename_expand (filename);
   if (rdir == NULL)
     return GNUNET_SYSERR;
   len = strlen (rdir);
@@ -1367,7 +1367,7 @@
  *
  * @param cfg configuration to use (determines HOME)
  * @param serviceName name of the service
- * @param varargs is NULL-terminated list of
+ * @param ... is NULL-terminated list of
  *                path components to append to the
  *                private directory name.
  * @return the constructed filename

Modified: gnunet/src/util/network.c
===================================================================
--- gnunet/src/util/network.c   2009-10-06 11:58:00 UTC (rev 9127)
+++ gnunet/src/util/network.c   2009-10-07 11:10:42 UTC (rev 9128)
@@ -384,22 +384,26 @@
 
 /**
  * Make a non-inheritable to child processes
- * @param socket
+ *
+ * @param h the socket to make non-inheritable
  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
  * @warning Not implemented on Windows
  */
 int
 GNUNET_NETWORK_socket_set_inheritable (const struct GNUNET_NETWORK_Handle
-                                       *desc)
+                                       *h)
 {
 #ifdef MINGW
   errno = ENOSYS;
   return GNUNET_SYSERR;
 #else
-  return fcntl (desc->fd, F_SETFD,
-                fcntl (desc->fd,
-                       F_GETFD) | FD_CLOEXEC) ==
-    0 ? GNUNET_OK : GNUNET_SYSERR;
+  int i;
+
+  i = fcntl (h->fd, F_GETFD);
+  if (i == (i | FD_CLOEXEC))
+    return GNUNET_OK;
+  return (fcntl (h->fd, F_SETFD, i | FD_CLOEXEC) == 0)
+    ? GNUNET_OK : GNUNET_SYSERR;
 #endif
 }