From: Christian Grothoff <christian@grothoff.org>
Date: Fri, 25 Sep 2009 22:10:51 +0000 (+0000)
Subject: improving style and docs
X-Git-Tag: initial-import-from-subversion-38251~23461
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=f1b9c5c115139b02cac1cae4f053792e1e5b1ccb;p=oweals%2Fgnunet.git

improving style and docs
---

diff --git a/BUGS b/BUGS
index eca77db6a..31f791f72 100644
--- a/BUGS
+++ b/BUGS
@@ -115,3 +115,4 @@ sane end-user should care about this codebase yet anyway.
 * HOSTLIST:
   - implement advertising of hostlist URL
   - implement learning of hostlist URLs
+
diff --git a/TODO b/TODO
index fc76b9604..8f708df7e 100644
--- a/TODO
+++ b/TODO
@@ -177,3 +177,5 @@ Urgent items (before announcing ng.gnunet.org):
 * Remove KBlocks in gnunet-unindex (see discussion with Kenneth Almquist on gnunet-devs in 9/2009)
 * Allow checking of presence of search results and/or content via command-line tools
   (add options to gnunet-search / gnunet-download to limit search to local peer)
+* STATISTICS:
+  - should use BIO instead of mmap
diff --git a/src/fs/gnunet-directory.c b/src/fs/gnunet-directory.c
index 8fc477614..a5caaa53d 100644
--- a/src/fs/gnunet-directory.c
+++ b/src/fs/gnunet-directory.c
@@ -127,7 +127,7 @@ run (void *cls,
   len = (size_t) size;
   data = GNUNET_DISK_file_map (h,
 			       &map,
-			       GNUNET_DISK_MAP_READ,
+			       GNUNET_DISK_MAP_TYPE_READ,
 			       len);
   GNUNET_assert (NULL != data);
   GNUNET_FS_directory_list_contents (len,
diff --git a/src/include/gnunet_client_lib.h b/src/include/gnunet_client_lib.h
index fd9291598..17f17ab50 100644
--- a/src/include/gnunet_client_lib.h
+++ b/src/include/gnunet_client_lib.h
@@ -87,12 +87,13 @@ typedef void (*GNUNET_CLIENT_MessageHandler) (void *cls,
  *
  * @param sock the service
  * @param handler function to call with the message
- * @param cls closure for handler
+ * @param handler_cls closure for handler
  * @param timeout how long to wait until timing out
  */
 void GNUNET_CLIENT_receive (struct GNUNET_CLIENT_Connection *sock,
                             GNUNET_CLIENT_MessageHandler handler,
-                            void *cls, struct GNUNET_TIME_Relative timeout);
+                            void *handler_cls,
+			    struct GNUNET_TIME_Relative timeout);
 
 
 /**
diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h
index 614fd3824..402674f48 100644
--- a/src/include/gnunet_common.h
+++ b/src/include/gnunet_common.h
@@ -1,6 +1,6 @@
 /*
      This file is part of GNUnet.
-     (C) 2006 Christian Grothoff (and other contributing authors)
+     (C) 2006, 2009 Christian Grothoff (and other contributing authors)
 
      GNUnet is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License as published
@@ -413,11 +413,23 @@ unsigned long long GNUNET_htonll (unsigned long long n);
 
 /**
  * Like snprintf, just aborts if the buffer is of insufficient size.
+ *
+ * @param buf pointer to buffer that is written to
+ * @param size number of bytes in buf
+ * @param format format strings
+ * @param ... data for format string
+ * @return number of bytes written to buf or negative value on error
  */
 int GNUNET_snprintf (char *buf, size_t size, const char *format, ...);
 
+
 /**
  * Like asprintf, just portable.
+ *
+ * @param buf set to a buffer of sufficient size (allocated, caller must free)
+ * @param format format string (see printf, fprintf, etc.)
+ * @param ... data for format string
+ * @return number of bytes in "*buf" excluding 0-termination
  */
 int GNUNET_asprintf (char **buf, const char *format, ...);
 
@@ -429,15 +441,26 @@ int GNUNET_asprintf (char **buf, const char *format, ...);
  * memory is available.  Don't use GNUNET_xmalloc_ directly. Use the
  * GNUNET_malloc macro.
  * The memory will be zero'ed out.
+ *
+ * @param size number of bytes to allocate
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return allocated memory, never NULL
  */
 void *GNUNET_xmalloc_ (size_t size, const char *filename, int linenumber);
 
+
 /**
  * Allocate memory.  This function does not check if the
  * allocation request is within reasonable bounds, allowing
  * allocations larger than 40 MB.  If you don't expect the
  * possibility of very large allocations, use GNUNET_malloc instead.
  * The memory will be zero'ed out.
+ *
+ * @param size number of bytes to allocate
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return allocated memory, never NULL
  */
 void *GNUNET_xmalloc_unchecked_ (size_t size,
                                  const char *filename, int linenumber);
@@ -453,12 +476,20 @@ void *GNUNET_xrealloc_ (void *ptr,
  * Free memory. Merely a wrapper for the case that we
  * want to keep track of allocations.  Don't use GNUNET_xfree_
  * directly. Use the GNUNET_free macro.
+ *
+ * @param ptr pointer to memory to free
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
  */
 void GNUNET_xfree_ (void *ptr, const char *filename, int linenumber);
 
 
 /**
  * Dup a string. Don't call GNUNET_xstrdup_ directly. Use the GNUNET_strdup macro.
+ * @param str string to duplicate
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return the duplicated string
  */
 char *GNUNET_xstrdup_ (const char *str, const char *filename, int linenumber);
 
@@ -474,6 +505,8 @@ char *GNUNET_xstrdup_ (const char *str, const char *filename, int linenumber);
  * @param elementSize the size of the elements of the array
  * @param oldCount address of the number of elements in the *old array
  * @param newCount number of elements in the new array, may be 0 (then *old will be NULL afterwards)
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
  */
 void GNUNET_xgrow_ (void **old,
                     size_t elementSize,
diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h
index 61dee9918..b376af3c8 100644
--- a/src/include/gnunet_container_lib.h
+++ b/src/include/gnunet_container_lib.h
@@ -344,15 +344,30 @@ int GNUNET_CONTAINER_meta_data_extract_from_file (struct
                                                   EXTRACTOR_ExtractorList *
                                                   extractors);
 
+
+/**
+ * Options for metadata serialization.
+ */
 enum GNUNET_CONTAINER_MetaDataSerializationOptions
 {
+  /**
+   * Serialize all of the data.
+   */
   GNUNET_CONTAINER_META_DATA_SERIALIZE_FULL = 0,
+
+  /**
+   * If not enough space is available, it is acceptable
+   * to only serialize some of the metadata.
+   */
   GNUNET_CONTAINER_META_DATA_SERIALIZE_PART = 1,
+
+  /**
+   * Speed is of the essence, do not allow compression.
+   */
   GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS = 2
 };
 
 
-
 /**
  * Serialize meta-data to target.
  *
@@ -631,6 +646,10 @@ void *GNUNET_CONTAINER_multihashmap_get_random (const struct
  * Insert an element into a DLL. Assumes
  * that head, tail and element are structs
  * with prev and next fields.
+ *
+ * @param head pointer to the head of the DLL
+ * @param tail pointer to the tail of the DLL
+ * @param element element to insert
  */
 #define GNUNET_CONTAINER_DLL_insert(head,tail,element) \
   (element)->next = (head); \
@@ -645,6 +664,11 @@ void *GNUNET_CONTAINER_multihashmap_get_random (const struct
  * Insert an element into a DLL after the given other
  * element.  Insert at the head if the other
  * element is NULL.
+ *
+ * @param head pointer to the head of the DLL
+ * @param tail pointer to the tail of the DLL
+ * @param other prior element, NULL for insertion at head of DLL
+ * @param element element to insert
  */
 #define GNUNET_CONTAINER_DLL_insert_after(head,tail,other,element) \
   (element)->prev = (other); \
@@ -670,6 +694,10 @@ void *GNUNET_CONTAINER_multihashmap_get_random (const struct
  * Remove an element from a DLL. Assumes
  * that head, tail and element are structs
  * with prev and next fields.
+ *
+ * @param head pointer to the head of the DLL
+ * @param tail pointer to the tail of the DLL
+ * @param element element to remove
  */
 #define GNUNET_CONTAINER_DLL_remove(head,tail,element) \
   if ((element)->prev == NULL) \
@@ -766,6 +794,9 @@ int GNUNET_CONTAINER_heap_iterate (struct GNUNET_CONTAINER_Heap *heap,
 /**
  * Inserts a new item into the heap, item is always neighbor now.
  * @param heap the heap
+ * @param element element to insert
+ * @param cost cost of the element
+ * @return FIXME
  */
 int
 GNUNET_CONTAINER_heap_insert (struct GNUNET_CONTAINER_Heap *heap,
@@ -795,7 +826,10 @@ void *GNUNET_CONTAINER_heap_peek (struct GNUNET_CONTAINER_Heap *heap);
  * Removes any node from the tree based on the neighbor given, does
  * not traverse the tree (backpointers) but may take more time due to
  * percolation of nodes.
+ *
  * @param heap the heap
+ * @param element element to remove
+ * @return FIXME
  */
 void *GNUNET_CONTAINER_heap_remove_node (struct GNUNET_CONTAINER_Heap *heap,
                                          void *element);
@@ -807,7 +841,7 @@ void *GNUNET_CONTAINER_heap_remove_node (struct GNUNET_CONTAINER_Heap *heap,
  * @param heap the heap
  * @param element the element for which the cost is updated
  * @param new_cost new cost for the element
- * @return WHAT?
+ * @return FIXME
  */
 int
 GNUNET_CONTAINER_heap_update_cost (struct GNUNET_CONTAINER_Heap *heap,
diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index 9303aa98c..9b795cc75 100644
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -43,10 +43,20 @@ extern "C"
 #include "gnunet_common.h"
 #include "gnunet_scheduler_lib.h"
 
-
+/**
+ * Desired quality level for cryptographic operations.
+ */
 enum GNUNET_CRYPTO_Quality
 {
+  /**
+   * No good quality of the operation is needed (i.e.,
+   * random numbers can be pseudo-random).
+   */
   GNUNET_CRYPTO_QUALITY_WEAK,
+
+  /**
+   * High-quality operations are desired.
+   */
   GNUNET_CRYPTO_QUALITY_STRONG
 };
 
@@ -242,6 +252,8 @@ unsigned int *GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode,
 
 /**
  * Create a new Session key.
+ *
+ * @param key key to initialize
  */
 void GNUNET_CRYPTO_aes_create_session_key (struct GNUNET_CRYPTO_AesSessionKey
                                            *key);
@@ -250,6 +262,7 @@ void GNUNET_CRYPTO_aes_create_session_key (struct GNUNET_CRYPTO_AesSessionKey
 /**
  * Check that a new session key is well-formed.
  *
+ * @param key key to check
  * @return GNUNET_OK if the key is valid
  */
 int GNUNET_CRYPTO_aes_check_session_key (const struct
@@ -320,6 +333,9 @@ int GNUNET_CRYPTO_hash_from_string (const char *enc,
  * a.a or a.e (they're used elsewhere), and
  * be somewhat consistent. And of course, the
  * result should be a positive number.
+ *
+ * @param a some hash code
+ * @param b some hash code
  * @return number between 0 and 65536
  */
 uint32_t GNUNET_CRYPTO_hash_distance_u32 (const GNUNET_HashCode * a,
@@ -372,6 +388,9 @@ void GNUNET_CRYPTO_hash_file (struct GNUNET_SCHEDULER_Handle *sched,
 
 /**
  * Create a random hash code.
+ *
+ * @param mode desired quality level
+ * @param result hash code that is randomized
  */
 void GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
 				       GNUNET_HashCode * result);
@@ -379,6 +398,10 @@ void GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
 
 /**
  * compute result(delta) = b - a
+ *
+ * @param a some hash code
+ * @param b some hash code
+ * @param result set to b - a 
  */
 void GNUNET_CRYPTO_hash_difference (const GNUNET_HashCode * a,
                                     const GNUNET_HashCode * b,
@@ -387,6 +410,10 @@ void GNUNET_CRYPTO_hash_difference (const GNUNET_HashCode * a,
 
 /**
  * compute result(b) = a + delta
+ *
+ * @param a some hash code
+ * @param delta some hash code
+ * @param result set to a + delta
  */
 void GNUNET_CRYPTO_hash_sum (const GNUNET_HashCode * a,
                              const GNUNET_HashCode * delta,
@@ -395,6 +422,10 @@ void GNUNET_CRYPTO_hash_sum (const GNUNET_HashCode * a,
 
 /**
  * compute result = a ^ b
+ *
+ * @param a some hash code
+ * @param b some hash code
+ * @param result set to a ^ b 
  */
 void GNUNET_CRYPTO_hash_xor (const GNUNET_HashCode * a,
                              const GNUNET_HashCode * b,
@@ -403,6 +434,10 @@ void GNUNET_CRYPTO_hash_xor (const GNUNET_HashCode * a,
 
 /**
  * Convert a hashcode into a key.
+ *
+ * @param hc hash code that serves to generate the key
+ * @param skey set to a valid session key
+ * @param iv set to a valid initialization vector
  */
 void GNUNET_CRYPTO_hash_to_aes_key (const GNUNET_HashCode * hc,
                                     struct GNUNET_CRYPTO_AesSessionKey *skey,
@@ -413,6 +448,7 @@ void GNUNET_CRYPTO_hash_to_aes_key (const GNUNET_HashCode * hc,
 
 /**
  * Obtain a bit from a hashcode.
+ *
  * @param code the GNUNET_CRYPTO_hash to index bit-wise
  * @param bit index into the hashcode, [0...159]
  * @return Bit \a bit from hashcode \a code, -1 for invalid index
@@ -424,6 +460,9 @@ int GNUNET_CRYPTO_hash_get_bit (const GNUNET_HashCode * code,
 /**
  * Compare function for HashCodes, producing a total ordering
  * of all hashcodes.
+ *
+ * @param h1 some hash code
+ * @param h2 some hash code
  * @return 1 if h1 > h2, -1 if h1 < h2 and 0 if h1 == h2.
  */
 int GNUNET_CRYPTO_hash_cmp (const GNUNET_HashCode * h1,
@@ -433,6 +472,10 @@ int GNUNET_CRYPTO_hash_cmp (const GNUNET_HashCode * h1,
 /**
  * Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
  * in the XOR metric (Kademlia).
+ *
+ * @param h1 some hash code
+ * @param h2 some hash code
+ * @param target some hash code
  * @return -1 if h1 is closer, 1 if h2 is closer and 0 if h1==h2.
  */
 int GNUNET_CRYPTO_hash_xorcmp (const GNUNET_HashCode * h1,
@@ -442,6 +485,8 @@ int GNUNET_CRYPTO_hash_xorcmp (const GNUNET_HashCode * h1,
 
 /**
  * Create a new private key. Caller must free return value.
+ *
+ * @return fresh private key
  */
 struct GNUNET_CRYPTO_RsaPrivateKey *GNUNET_CRYPTO_rsa_key_create (void);
 
@@ -458,6 +503,7 @@ struct GNUNET_CRYPTO_RsaPrivateKey *GNUNET_CRYPTO_rsa_key_create (void);
  * are invalid the old file is deleted and a fresh key is
  * created.
  *
+ * @param filename name of file to use for storage
  * @return new private key, NULL on error (for example,
  *   permission denied)
  */
@@ -468,6 +514,9 @@ struct GNUNET_CRYPTO_RsaPrivateKey
 /**
  * Deterministically (!) create a private key using only the
  * given HashCode as input to the PRNG.
+ *
+ * @param input "random" input to PRNG
+ * @return some private key purely dependent on input
  */
 struct GNUNET_CRYPTO_RsaPrivateKey
   *GNUNET_CRYPTO_rsa_key_create_from_hash (const GNUNET_HashCode * input);
@@ -482,13 +531,15 @@ void GNUNET_CRYPTO_rsa_key_free (struct GNUNET_CRYPTO_RsaPrivateKey *hostkey);
 
 /**
  * Extract the public key of the host.
- * @param result where to write the result.
+ *
+ * @param priv the private key
+ * @param pub where to write the public key
  */
 void GNUNET_CRYPTO_rsa_key_get_public (const struct
-                                       GNUNET_CRYPTO_RsaPrivateKey *hostkey,
+                                       GNUNET_CRYPTO_RsaPrivateKey *priv,
                                        struct
                                        GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded
-                                       *result);
+                                       *pub);
 
 
 /**
@@ -562,7 +613,7 @@ int GNUNET_CRYPTO_rsa_verify (uint32_t purpose,
 /**
  * This function should only be called in testcases
  * where strong entropy gathering is not desired
- * (for example, for hostkey generation).
+ * (for example, for hostkey generation). 
  */
 void GNUNET_CRYPTO_random_disable_entropy_gathering (void);
 
diff --git a/src/include/gnunet_datastore_service.h b/src/include/gnunet_datastore_service.h
index bcc89a8e1..aa35c82ee 100644
--- a/src/include/gnunet_datastore_service.h
+++ b/src/include/gnunet_datastore_service.h
@@ -41,14 +41,42 @@ extern "C"
 #endif
 #endif
 
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_ANY 0
+
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_DBLOCK 1
+
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_IBLOCK 2
+
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_KBLOCK 3
+
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_SBLOCK 4
+
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_ONDEMAND 5
+
+/**
+ * FIXME.
+ */
 #define GNUNET_DATASTORE_BLOCKTYPE_SKBLOCK 6 /* not yet used */
 
+
 /**
  * Handle to the datastore service.
  */
diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h
index 4d09d4c99..137d4a452 100644
--- a/src/include/gnunet_disk_lib.h
+++ b/src/include/gnunet_disk_lib.h
@@ -53,25 +53,70 @@ extern "C"
 #endif
 
 
-/* Open the file for reading */
-#define GNUNET_DISK_OPEN_READ           1
-/* Open the file for writing */
-#define GNUNET_DISK_OPEN_WRITE          2
-/* Open the file for both reading and writing */
-#define GNUNET_DISK_OPEN_READWRITE      3
-/* Fail if file already exists */
-#define GNUNET_DISK_OPEN_FAILIFEXISTS   4
-/* Truncate file if it exists */
-#define GNUNET_DISK_OPEN_TRUNCATE       8
-/* Create file if it doesn't exist */
-#define GNUNET_DISK_OPEN_CREATE         16
-/* Append to the file */
-#define GNUNET_DISK_OPEN_APPEND         32
-
-#define GNUNET_DISK_MAP_READ    1
-#define GNUNET_DISK_MAP_WRITE   2
-#define GNUNET_DISK_MAP_READWRITE 3
+/**
+ * Specifies how a file should be opened.
+ */
+enum GNUNET_DISK_OpenFlags
+  {
+
+    /**
+     * Open the file for reading 
+     */
+    GNUNET_DISK_OPEN_READ = 1,
+    
+    /**
+     * Open the file for writing 
+     */
+    GNUNET_DISK_OPEN_WRITE = 2,
+    
+    /**
+     * Open the file for both reading and writing 
+     */
+    GNUNET_DISK_OPEN_READWRITE = 3,
+    
+    /**
+     * Fail if file already exists 
+     */
+    GNUNET_DISK_OPEN_FAILIFEXISTS = 4,
+    
+    /**
+     * Truncate file if it exists 
+     */
+    GNUNET_DISK_OPEN_TRUNCATE = 8,
+    
+    /**
+     * Create file if it doesn't exist 
+     */
+    GNUNET_DISK_OPEN_CREATE = 16,
+
+    /**
+     * Append to the file 
+     */
+    GNUNET_DISK_OPEN_APPEND = 32
+  };
 
+/**
+ * Specifies what type of memory map is desired.
+ */
+enum GNUNET_DISK_MapType
+  {
+    /**
+     * Read-only memory map.
+     */
+    GNUNET_DISK_MAP_TYPE_READ = 1,
+
+    /**
+     * Write-able memory map.
+     */
+    GNUNET_DISK_MAP_TYPE_WRITE = 2,
+    /**
+     * Read-write memory map.
+     */
+    GNUNET_DISK_MAP_TYPE_READWRITE = 3
+  };
+
+
+// FIXME: use enum here!
 #define GNUNET_DISK_PERM_USER_READ      1
 #define GNUNET_DISK_PERM_USER_WRITE     2
 #define GNUNET_DISK_PERM_USER_EXEC      4
@@ -82,10 +127,24 @@ extern "C"
 #define GNUNET_DISK_PERM_OTHER_WRITE    128
 #define GNUNET_DISK_PERM_OTHER_EXEC     256
 
+/**
+ * Constants for specifying how to seek.
+ */
 enum GNUNET_DISK_Seek 
   {
+    /**
+     * Seek an absolute position (from the start of the file).
+     */
     GNUNET_DISK_SEEK_SET, 
+
+    /**
+     * Seek a relative position (from the current offset).
+     */
     GNUNET_DISK_SEEK_CUR, 
+    
+    /**
+     * Seek an absolute position from the end of the file.
+     */
     GNUNET_DISK_SEEK_END
   };
 
@@ -111,7 +170,8 @@ int GNUNET_DISK_handle_invalid (const struct GNUNET_DISK_FileHandle *h);
  * Check that fil corresponds to a filename
  * (of a file that exists and that is not a directory).
  *
- * @returns GNUNET_YES if yes, GNUNET_NO if not a file, GNUNET_SYSERR if something
+ * @param fil filename to check
+ * @return GNUNET_YES if yes, GNUNET_NO if not a file, GNUNET_SYSERR if something
  * else (will print an error message in that case, too).
  */
 int GNUNET_DISK_file_test (const char *fil);
@@ -149,7 +209,14 @@ int GNUNET_DISK_file_size (const char *filename,
 
 
 /**
- * FIXME.
+ * Obtain some unique identifiers for the given file
+ * that can be used to identify it in the local system.
+ * This function is used between GNUnet processes to
+ * quickly check if two files with the same absolute path
+ * are actually identical.  The two processes represent
+ * the same peer but may communicate over the network
+ * (and the file may be on an NFS volume).  This function
+ * may not be supported on all operating systems.
  *
  * @param filename name of the file
  * @param dev set to the device ID
@@ -170,17 +237,20 @@ int GNUNET_DISK_file_get_identifiers (const char *filename,
  *         file on disk in directory for temporary files
  */
 char *
-GNUNET_DISK_mktemp (const char *t);
+GNUNET_DISK_mktemp (const char *template);
 
 
 /**
- * Open a file
+ * Open a file.
+ *
  * @param fn file name to be opened
  * @param flags opening flags, a combination of GNUNET_DISK_OPEN_xxx bit flags
- * @param perm permissions for the newly created file
+ * @param ... permissions for the newly created file (only required if creation is possible)
  * @return IO handle on success, NULL on error
  */
-struct GNUNET_DISK_FileHandle *GNUNET_DISK_file_open (const char *fn, int flags, ...);
+struct GNUNET_DISK_FileHandle *GNUNET_DISK_file_open (const char *fn,
+						      enum GNUNET_DISK_OpenFlags flags,
+						      ...);
 
 /**
  * Creates an interprocess channel
@@ -207,7 +277,8 @@ int GNUNET_DISK_file_close (struct GNUNET_DISK_FileHandle *h);
 /**
  * Get the handle to a particular pipe end
  * @param p pipe
- * @param n number of the end
+ * @param n number of the end (0 or 1); FIXME: use enum here!
+ * @return handle for the respective end
  */
 const struct GNUNET_DISK_FileHandle *GNUNET_DISK_pipe_handle (const struct
 							GNUNET_DISK_PipeHandle
@@ -359,6 +430,7 @@ int GNUNET_DISK_directory_create_for_file (const char *filename);
  * does not exist.  Will log errors if GNUNET_SYSERR is
  * returned.
  *
+ * @param fil filename to test
  * @return GNUNET_YES if yes, GNUNET_NO if does not exist, GNUNET_SYSERR
  *   on any error and if exists but not directory
  */
@@ -385,22 +457,24 @@ int GNUNET_DISK_directory_create (const char *dir);
 
 
 /**
- * Lock a part of a file
+ * Lock a part of a file.
+ *
  * @param fh file handle
- * @lockStart absolute position from where to lock
- * @lockEnd absolute position until where to lock
- * @excl GNUNET_YES for an exclusive lock
+ * @param lockStart absolute position from where to lock
+ * @param lockEnd absolute position until where to lock
+ * @param excl GNUNET_YES for an exclusive lock
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
 GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, off_t lockStart,
     off_t lockEnd, int excl);
 
+
 /**
  * Unlock a part of a file
  * @param fh file handle
- * @lockStart absolute position from where to unlock
- * @lockEnd absolute position until where to unlock
+ * @param lockStart absolute position from where to unlock
+ * @param lockEnd absolute position until where to unlock
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
@@ -431,6 +505,7 @@ int GNUNET_DISK_file_change_owner (const char *filename, const char *user);
  * a directory, end the last argument in '/' (or pass
  * DIR_SEPARATOR_STR as the last argument before NULL).
  *
+ * @param cfg configuration to use
  * @param serviceName name of the service asking
  * @param varargs is NULL-terminated list of
  *                path components to append to the
@@ -450,13 +525,13 @@ struct GNUNET_DISK_MapHandle;
  * Map a file into memory
  * @param h open file handle
  * @param m handle to the new mapping (will be set)
- * @param access access specification, GNUNET_DISK_MAP_xxx
+ * @param access access specification, GNUNET_DISK_MAP_TYPE_xxx
  * @param len size of the mapping
  * @return pointer to the mapped memory region, NULL on failure
  */
 void *GNUNET_DISK_file_map (const struct GNUNET_DISK_FileHandle *h, 
 			    struct GNUNET_DISK_MapHandle **m,
-			    int access, size_t len);
+			    enum GNUNET_DISK_MapType access, size_t len);
 
 /**
  * Unmap a file
diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index 35db3f6d1..44525e2f2 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -197,22 +197,37 @@ int GNUNET_GETOPT_run (const char *binaryName,
                        const struct GNUNET_GETOPT_CommandLineOption
                        *allOptions, unsigned int argc, char *const *argv);
 
+/**
+ * FIXME
+ */
 int GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext
                              *ctx, void *scls, const char *option,
                              const char *value);
 
+/**
+ * FIXME
+ */
 int GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext
                             *ctx, void *scls, const char *option,
                             const char *value);
 
+/**
+ * FIXME
+ */
 int GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext
                            *ctx, void *scls, const char *option,
                            const char *value);
 
+/**
+ * FIXME
+ */
 int GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext
                               *ctx, void *scls, const char *option,
                               const char *value);
 
+/**
+ * FIXME
+ */
 int
 GNUNET_GETOPT_increment_value (struct
                                GNUNET_GETOPT_CommandLineProcessorContext *ctx,
@@ -221,11 +236,17 @@ GNUNET_GETOPT_increment_value (struct
 
 /* *************** internal prototypes - use macros above! ************* */
 
+/**
+ * FIXME
+ */
 int GNUNET_GETOPT_format_help_ (struct
                                 GNUNET_GETOPT_CommandLineProcessorContext
                                 *ctx, void *scls, const char *option,
                                 const char *value);
 
+/**
+ * FIXME
+ */
 int GNUNET_GETOPT_print_version_ (struct
                                   GNUNET_GETOPT_CommandLineProcessorContext
                                   *ctx, void *scls, const char *option,
diff --git a/src/include/gnunet_network_lib.h b/src/include/gnunet_network_lib.h
index 97fcf2618..492713c46 100644
--- a/src/include/gnunet_network_lib.h
+++ b/src/include/gnunet_network_lib.h
@@ -65,7 +65,9 @@ GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc,
 			      socklen_t *address_len);
 
 /**
- * Make a non-inheritable to child processes
+ * Make a non-inheritable to child processes (sets the
+ * close-on-exec flag).
+ *
  * @param socket
  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
  * @warning Not implemented on Windows
@@ -123,10 +125,12 @@ int GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, int
 
 /**
  * Read data from a connected socket
+ *
  * @param desc socket
  * @param buffer buffer
  * @param length length of buffer
  * @param flags type of message reception
+ * @return number of bytes read
  */
 ssize_t GNUNET_NETWORK_socket_recv (const struct GNUNET_NETWORK_Handle *desc, void *buffer,
                         size_t length, int flags);
@@ -149,7 +153,8 @@ int GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds,
  * @param doBlock blocking mode
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
-int GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, int doBlock);
+int GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, 
+					int doBlock);
 
 /**
  * Send data
@@ -207,8 +212,9 @@ int GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, int how)
 struct GNUNET_NETWORK_Handle *GNUNET_NETWORK_socket_socket (int domain, int type, int protocol);
 
 /**
- * Reset FD set
- * @param fds fd set
+ * Reset FD set (clears all file descriptors).
+ *
+ * @param fds fd set to clear
  */
 void GNUNET_NETWORK_fdset_zero(struct GNUNET_NETWORK_FDSet *fds);
 
@@ -218,7 +224,8 @@ void GNUNET_NETWORK_fdset_zero(struct GNUNET_NETWORK_FDSet *fds);
  * @param desc socket to add
  */
 void GNUNET_NETWORK_fdset_set(struct GNUNET_NETWORK_FDSet *fds,
-    const struct GNUNET_NETWORK_Handle *desc);
+			      const struct GNUNET_NETWORK_Handle *desc);
+
 
 /**
  * Check whether a socket is part of the fd set
@@ -226,7 +233,7 @@ void GNUNET_NETWORK_fdset_set(struct GNUNET_NETWORK_FDSet *fds,
  * @param desc socket
  */
 int GNUNET_NETWORK_fdset_isset(const struct GNUNET_NETWORK_FDSet *fds,
-    const struct GNUNET_NETWORK_Handle *desc);
+			       const struct GNUNET_NETWORK_Handle *desc);
 
 /**
  * Add one fd set to another
@@ -234,7 +241,7 @@ int GNUNET_NETWORK_fdset_isset(const struct GNUNET_NETWORK_FDSet *fds,
  * @param src the fd set to add from
  */
 void GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst,
-    const struct GNUNET_NETWORK_FDSet *src);
+			       const struct GNUNET_NETWORK_FDSet *src);
 
 /**
  * Copy one fd set to another
@@ -242,7 +249,7 @@ void GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst,
  * @param from source
  */
 void GNUNET_NETWORK_fdset_copy(struct GNUNET_NETWORK_FDSet *to,
-    const struct GNUNET_NETWORK_FDSet *from);
+			       const struct GNUNET_NETWORK_FDSet *from);
 
 /**
  * Copy a native fd set
@@ -250,8 +257,9 @@ void GNUNET_NETWORK_fdset_copy(struct GNUNET_NETWORK_FDSet *to,
  * @param from native source set
  * @param the biggest socket number in from + 1
  */
-void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, const fd_set *from,
-    int nfds);
+void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, 
+				       const fd_set *from,
+				       int nfds);
 
 /**
  * Add a file handle to the fd set
@@ -259,7 +267,7 @@ void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, const fd
  * @param h the file handle to add
  */
 void GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds,
-    const struct GNUNET_DISK_FileHandle *h);
+				      const struct GNUNET_DISK_FileHandle *h);
 
 /**
  * Check if a file handle is part of an fd set
@@ -268,7 +276,7 @@ void GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds,
  * @return GNUNET_YES if the file handle is part of the set
  */
 int GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds,
-    const struct GNUNET_DISK_FileHandle *h);
+				       const struct GNUNET_DISK_FileHandle *h);
 
 /**
  * Checks if two fd sets overlap
@@ -276,7 +284,8 @@ int GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds,
  * @param fds2 second fd set
  * @return GNUNET_YES if they do overlap, GNUNET_NO otherwise
  */
-int GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, const struct GNUNET_NETWORK_FDSet *fds2);
+int GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, 
+				  const struct GNUNET_NETWORK_FDSet *fds2);
 
 /**
  * Creates an fd set
diff --git a/src/include/gnunet_os_lib.h b/src/include/gnunet_os_lib.h
index 3af4f72a3..3bc6eb5f9 100644
--- a/src/include/gnunet_os_lib.h
+++ b/src/include/gnunet_os_lib.h
@@ -50,11 +50,36 @@ extern "C"
  */
 enum GNUNET_OS_InstallationPathKind
 {
+  /**
+   * Return the "PREFIX" directory given to configure.
+   */
   GNUNET_OS_IPK_PREFIX,
+
+  /**
+   * Return the directory where the program binaries are installed. (bin/)
+   */
   GNUNET_OS_IPK_BINDIR,
+
+  /**
+   * Return the directory where libraries are installed. (lib/)
+   */
   GNUNET_OS_IPK_LIBDIR,
+
+  /**
+   * Return the directory where data is installed (share/)
+   */
   GNUNET_OS_IPK_DATADIR,
+
+  /**
+   * Return the directory where translations are installed (share/locale/)
+   */
   GNUNET_OS_IPK_LOCALEDIR,
+
+  /**
+   * Return the installation directory of this application, not
+   * the one of the overall GNUnet installation (in case they
+   * are different).
+   */
   GNUNET_OS_IPK_SELF_PREFIX
 };
 
@@ -64,10 +89,30 @@ enum GNUNET_OS_InstallationPathKind
  */
 enum GNUNET_OS_ProcessStatusType
 {
+  /**
+   * The process is not known to the OS (or at
+   * least not one of our children).
+   */
   GNUNET_OS_PROCESS_UNKNOWN,
+
+  /**
+   * The process is still running.
+   */
   GNUNET_OS_PROCESS_RUNNING,
+
+  /**
+   * The process is paused (but could be resumed).
+   */
   GNUNET_OS_PROCESS_STOPPED,
+
+  /**
+   * The process exited with a return code.
+   */
   GNUNET_OS_PROCESS_EXITED,
+
+  /**
+   * The process was killed by a signal.
+   */
   GNUNET_OS_PROCESS_SIGNALED
 };
 
@@ -103,10 +148,11 @@ typedef int (*GNUNET_OS_NetworkInterfaceProcessor) (void *cls,
 
 /**
  * @brief Enumerate all network interfaces
- * @param callback the callback function
+ * @param proc the callback function
+ * @param proc_cls closure for proc
  */
 void GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor
-                                        proc, void *cls);
+                                        proc, void *proc_cls);
 
 /**
  * Get the current CPU load.
diff --git a/src/include/gnunet_plugin_lib.h b/src/include/gnunet_plugin_lib.h
index e4f603c4e..b8c7b99fe 100644
--- a/src/include/gnunet_plugin_lib.h
+++ b/src/include/gnunet_plugin_lib.h
@@ -41,6 +41,11 @@ extern "C"
 
 /**
  * Signature of any function exported by a plugin.
+ *
+ * @param arg argument to the function (context)
+ * @return some pointer, NULL if the plugin was
+ *         shutdown or if there was an error, otherwise
+ *         the plugin's API on success
  */
 typedef void *(*GNUNET_PLUGIN_Callback) (void *arg);
 
@@ -55,7 +60,7 @@ typedef void *(*GNUNET_PLUGIN_Callback) (void *arg);
  *
  * @param library_name name of the plugin to load
  * @param arg argument to the plugin initialization function
- * @return whatever the initialization function returned
+ * @return whatever the initialization function returned, NULL on error
  */
 void *GNUNET_PLUGIN_load (const char *library_name, void *arg);
 
@@ -66,7 +71,8 @@ void *GNUNET_PLUGIN_load (const char *library_name, void *arg);
  *
  * @param library_name name of the plugin to unload
  * @param arg argument to the plugin shutdown function
- * @return whatever the shutdown function returned
+ * @return whatever the shutdown function returned, typically NULL
+ *         or a "char *" representing the error message
  */
 void *GNUNET_PLUGIN_unload (const char *library_name, void *arg);
 
diff --git a/src/include/gnunet_signal_lib.h b/src/include/gnunet_signal_lib.h
index af1ec0de4..e386ccc0e 100644
--- a/src/include/gnunet_signal_lib.h
+++ b/src/include/gnunet_signal_lib.h
@@ -35,6 +35,10 @@ extern "C"
 #endif
 #endif
 
+/**
+ * Context created when a signal handler is installed;
+ * can be used to restore it to the previous state later.
+ */
 struct GNUNET_SIGNAL_Context;
 
 /**
@@ -50,6 +54,10 @@ typedef void (*GNUNET_SIGNAL_Handler) (void);
 /**
  * Install a signal handler that will be run if the
  * given signal is received.
+ *
+ * @param signal the number of the signal
+ * @param handler the function to call
+ * @return context that can be used to restore, NULL on error
  */
 struct GNUNET_SIGNAL_Context *GNUNET_SIGNAL_handler_install (int signal,
                                                              GNUNET_SIGNAL_Handler
@@ -57,6 +65,9 @@ struct GNUNET_SIGNAL_Context *GNUNET_SIGNAL_handler_install (int signal,
 
 /**
  * Uninstall a previously installed signal hander.
+ *
+ * @param ctx context that was returned when the
+ *            signal handler was installed
  */
 void GNUNET_SIGNAL_handler_uninstall (struct GNUNET_SIGNAL_Context *ctx);
 
diff --git a/src/include/gnunet_strings_lib.h b/src/include/gnunet_strings_lib.h
index ab0f1ad7c..a466074a3 100644
--- a/src/include/gnunet_strings_lib.h
+++ b/src/include/gnunet_strings_lib.h
@@ -52,25 +52,33 @@ extern "C"
 
 /**
  * Convert a given filesize into a fancy human-readable format.
+ *
+ * @param size number of bytes
+ * @return fancy representation of the size (possibly rounded) for humans
  */
 char *GNUNET_STRINGS_byte_size_fancy (unsigned long long size);
 
+
 /**
  * Convert the len characters long character sequence
  * given in input that is in the given charset
  * to UTF-8.
  *
+ * @param input the input string (not necessarily 0-terminated)
+ * @param len the number of bytes in the input
+ * @param charset character set to convert from
  * @return the converted string (0-terminated)
  */
 char *GNUNET_STRINGS_to_utf8 (const char *input,
                               size_t len, const char *charset);
 
+
 /**
  * Complete filename (a la shell) from abbrevition.
  *
  * @param fil the name of the file, may contain ~/ or
  *        be relative to the current directory
- * @returns the full file name,
+ * @return the full file name,
  *          NULL is returned on error
  */
 char *GNUNET_STRINGS_filename_expand (const char *fil);
@@ -87,12 +95,19 @@ char *GNUNET_STRINGS_filename_expand (const char *fil);
  * used to parse the buffer back into individual
  * strings.
  *
+ * @param buffer the buffer to fill with strings, can
+ *               be NULL in which case only the necessary
+ *               amount of space will be calculated
+ * @param size number of bytes available in buffer
+ * @param count number of strings that follow
+ * @param ... count 0-terminated strings to copy to buffer
  * @return number of bytes written to the buffer
  *         (or number of bytes that would have been written)
  */
-unsigned int GNUNET_STRINGS_buffer_fill (char *buffer,
-                                         unsigned int size,
-                                         unsigned int count, ...);
+size_t GNUNET_STRINGS_buffer_fill (char *buffer,
+				   size_t size,
+				   unsigned int count, ...);
+
 
 /**
  * Given a buffer of a given size, find "count"
@@ -104,11 +119,12 @@ unsigned int GNUNET_STRINGS_buffer_fill (char *buffer,
  * @param buffer the buffer to parse
  * @param size size of the buffer
  * @param count number of strings to locate
+ * @param ... pointers to where to store the strings
  * @return offset of the character after the last 0-termination
  *         in the buffer, or 0 on error.
  */
 unsigned int GNUNET_STRINGS_buffer_tokenize (const char *buffer,
-                                             unsigned int size,
+                                             size_t size,
                                              unsigned int count, ...);
 
 
@@ -131,6 +147,7 @@ char *GNUNET_STRINGS_absolute_time_to_string (struct GNUNET_TIME_Absolute t);
  */
 char *GNUNET_STRINGS_relative_time_to_string (struct GNUNET_TIME_Relative
                                               delta);
+
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
diff --git a/src/include/gnunet_time_lib.h b/src/include/gnunet_time_lib.h
index e4b9dd970..3b901f526 100644
--- a/src/include/gnunet_time_lib.h
+++ b/src/include/gnunet_time_lib.h
@@ -43,6 +43,9 @@ extern "C"
  */
 struct GNUNET_TIME_Absolute
 {
+  /**
+   * The actual value.
+   */
   uint64_t value;
 };
 
@@ -52,6 +55,9 @@ struct GNUNET_TIME_Absolute
  */
 struct GNUNET_TIME_Relative
 {
+  /**
+   * The actual value.
+   */
   uint64_t value;
 };
 
@@ -61,6 +67,9 @@ struct GNUNET_TIME_Relative
  */
 struct GNUNET_TIME_RelativeNBO
 {
+  /**
+   * The actual value (in network byte order).
+   */
   uint64_t value__ GNUNET_PACKED;
 };
 
@@ -70,22 +79,61 @@ struct GNUNET_TIME_RelativeNBO
  */
 struct GNUNET_TIME_AbsoluteNBO
 {
+  /**
+   * The actual value (in network byte order).
+   */
   uint64_t value__ GNUNET_PACKED;
 };
 
 
 /**
- * @brief constants to specify time
+ * Relative time zero.
  */
 #define GNUNET_TIME_UNIT_ZERO     GNUNET_TIME_relative_get_zero()
+
+/**
+ * Absolute time zero.
+ */
 #define GNUNET_TIME_UNIT_ZERO_ABS GNUNET_TIME_absolute_get_zero()
+
+/**
+ * One millisecond, our basic time unit.
+ */
 #define GNUNET_TIME_UNIT_MILLISECONDS GNUNET_TIME_relative_get_unit()
+
+/**
+ * One second.
+ */
 #define GNUNET_TIME_UNIT_SECONDS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MILLISECONDS, 1000)
+
+/**
+ * One minute.
+ */
 #define GNUNET_TIME_UNIT_MINUTES GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_SECONDS, 60)
+
+/**
+ * One hour.
+ */
 #define GNUNET_TIME_UNIT_HOURS   GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MINUTES, 60)
+
+/**
+ * One day.
+ */
 #define GNUNET_TIME_UNIT_DAYS    GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_HOURS,   24)
+
+/**
+ * One week.
+ */
 #define GNUNET_TIME_UNIT_WEEKS   GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_DAYS,     7)
+
+/**
+ * One month (30 days).
+ */
 #define GNUNET_TIME_UNIT_MONTHS  GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_DAYS,    30)
+
+/**
+ * One year (365 days).
+ */
 #define GNUNET_TIME_UNIT_YEARS   GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_DAYS,   365)
 
 /**
@@ -136,6 +184,7 @@ struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_get (void);
  * Convert relative time to an absolute time in the
  * future.
  *
+ * @param rel relative time to convert
  * @return timestamp that is "rel" in the future, or FOREVER if rel==FOREVER (or if we would overflow)
  */
 struct GNUNET_TIME_Absolute GNUNET_TIME_relative_to_absolute (struct
@@ -145,6 +194,8 @@ struct GNUNET_TIME_Absolute GNUNET_TIME_relative_to_absolute (struct
 /**
  * Return the minimum of two relative time values.
  *
+ * @param t1 first timestamp
+ * @param t2 other timestamp
  * @return timestamp that is smaller
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_relative_min (struct
@@ -157,6 +208,7 @@ struct GNUNET_TIME_Relative GNUNET_TIME_relative_min (struct
  * Given a timestamp in the future, how much time
  * remains until then?
  *
+ * @param future some absolute time, typically in the future
  * @return future - now, or 0 if now >= future, or FOREVER if future==FOREVER.
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_remaining (struct
@@ -184,6 +236,8 @@ struct GNUNET_TIME_Relative GNUNET_TIME_calculate_eta (struct GNUNET_TIME_Absolu
  * Use this function instead of actual subtraction to ensure that
  * "FOREVER" and overflows are handeled correctly.
  *
+ * @param start some absolute time
+ * @param end some absolute time (typically larger or equal to start)
  * @return 0 if start >= end; FOREVER if end==FOREVER; otherwise end - start
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_difference (struct
@@ -197,6 +251,7 @@ struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_difference (struct
  * Get the duration of an operation as the
  * difference of the current time and the given start time "hence".
  *
+ * @param hence some absolute time, typically in the past
  * @return aborts if hence==FOREVER, 0 if hence > now, otherwise now-hence.
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_duration (struct
@@ -208,6 +263,8 @@ struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_duration (struct
  * Add a given relative duration to the
  * given start time.
  *
+ * @param start some absolute time
+ * @param duration some relative time to add
  * @return FOREVER if either argument is FOREVER or on overflow; start+duration otherwise
  */
 struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_add (struct
@@ -220,6 +277,8 @@ struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_add (struct
 /**
  * Multiply relative time by a given factor.
  *
+ * @param rel some duration
+ * @param factor integer to multiply with
  * @return FOREVER if rel=FOREVER or on overflow; otherwise rel*factor
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_relative_multiply (struct
@@ -231,6 +290,8 @@ struct GNUNET_TIME_Relative GNUNET_TIME_relative_multiply (struct
 /**
  * Add relative times together.
  *
+ * @param a1 some relative time
+ * @param a2 some other relative time
  * @return FOREVER if either argument is FOREVER or on overflow; a1+a2 otherwise
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_relative_add (struct
@@ -242,6 +303,9 @@ struct GNUNET_TIME_Relative GNUNET_TIME_relative_add (struct
 
 /**
  * Convert relative time to network byte order.
+ * 
+ * @param a time to convert
+ * @return converted time value
  */
 struct GNUNET_TIME_RelativeNBO GNUNET_TIME_relative_hton (struct
                                                           GNUNET_TIME_Relative
@@ -249,6 +313,9 @@ struct GNUNET_TIME_RelativeNBO GNUNET_TIME_relative_hton (struct
 
 /**
  * Convert relative time from network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
  */
 struct GNUNET_TIME_Relative GNUNET_TIME_relative_ntoh (struct
                                                        GNUNET_TIME_RelativeNBO
@@ -256,6 +323,9 @@ struct GNUNET_TIME_Relative GNUNET_TIME_relative_ntoh (struct
 
 /**
  * Convert relative time to network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
  */
 struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton (struct
                                                           GNUNET_TIME_Absolute
@@ -263,6 +333,9 @@ struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton (struct
 
 /**
  * Convert relative time from network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
  */
 struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_ntoh (struct
                                                        GNUNET_TIME_AbsoluteNBO
diff --git a/src/statistics/gnunet-service-statistics.c b/src/statistics/gnunet-service-statistics.c
index e4c3fe040..20dd10586 100644
--- a/src/statistics/gnunet-service-statistics.c
+++ b/src/statistics/gnunet-service-statistics.c
@@ -22,6 +22,9 @@
  * @file statistics/gnunet-service-statistics.c
  * @brief program that tracks statistics
  * @author Christian Grothoff
+ * 
+ * TODO:
+ * - use BIO for IO operations
  */
 #include "platform.h"
 #include "gnunet_disk_lib.h"
@@ -121,7 +124,7 @@ load (struct GNUNET_SERVER_Handle *server,
       GNUNET_free (fn);
       return;
     }
-  buf = GNUNET_DISK_file_map (fh, &mh, GNUNET_DISK_MAP_READ, sb.st_size);
+  buf = GNUNET_DISK_file_map (fh, &mh, GNUNET_DISK_MAP_TYPE_READ, sb.st_size);
   if (NULL == buf)
     {
       GNUNET_log_strerror_file (GNUNET_ERROR_TYPE_WARNING, "mmap", fn);
diff --git a/src/util/common_allocation.c b/src/util/common_allocation.c
index 749f824cd..2f78c98f6 100644
--- a/src/util/common_allocation.c
+++ b/src/util/common_allocation.c
@@ -171,6 +171,14 @@ GNUNET_xgrow_ (void **old,
 }
 
 
+/**
+ * Like asprintf, just portable.
+ *
+ * @param buf set to a buffer of sufficient size (allocated, caller must free)
+ * @param format format string (see printf, fprintf, etc.)
+ * @param ... data for format string
+ * @return number of bytes in "*buf" excluding 0-termination
+ */
 int
 GNUNET_asprintf (char **buf, const char *format, ...)
 {
@@ -187,6 +195,16 @@ GNUNET_asprintf (char **buf, const char *format, ...)
   return ret;
 }
 
+
+/**
+ * Like snprintf, just aborts if the buffer is of insufficient size.
+ *
+ * @param buf pointer to buffer that is written to
+ * @param size number of bytes in buf
+ * @param format format strings
+ * @param ... data for format string
+ * @return number of bytes written to buf or negative value on error
+ */
 int
 GNUNET_snprintf (char *buf, size_t size, const char *format, ...)
 {
diff --git a/src/util/disk.c b/src/util/disk.c
index 0aeab5b8b..9f2f8dcf7 100644
--- a/src/util/disk.c
+++ b/src/util/disk.c
@@ -1012,9 +1012,9 @@ GNUNET_DISK_file_change_owner (const char *filename, const char *user)
 /**
  * Lock a part of a file
  * @param fh file handle
- * @lockStart absolute position from where to lock
- * @lockEnd absolute position until where to lock
- * @excl GNUNET_YES for an exclusive lock
+ * @param lockStart absolute position from where to lock
+ * @param lockEnd absolute position until where to lock
+ * @param excl GNUNET_YES for an exclusive lock
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
@@ -1058,8 +1058,8 @@ GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, off_t lockStart,
 /**
  * Unlock a part of a file
  * @param fh file handle
- * @lockStart absolute position from where to unlock
- * @lockEnd absolute position until where to unlock
+ * @param lockStart absolute position from where to unlock
+ * @param lockEnd absolute position until where to unlock
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
@@ -1103,11 +1103,13 @@ GNUNET_DISK_file_unlock (struct GNUNET_DISK_FileHandle *fh, off_t unlockStart,
  * Open a file
  * @param fn file name to be opened
  * @param flags opening flags, a combination of GNUNET_DISK_OPEN_xxx bit flags
- * @param perm permissions for the newly created file
+ * @param ... permissions for the newly created file
  * @return IO handle on success, NULL on error
  */
 struct GNUNET_DISK_FileHandle *
-GNUNET_DISK_file_open (const char *fn, int flags, ...)
+GNUNET_DISK_file_open (const char *fn,
+		       enum GNUNET_DISK_OpenFlags flags, 
+		       ...)
 {
   char *expfn;
   struct GNUNET_DISK_FileHandle *ret;
@@ -1363,13 +1365,13 @@ struct GNUNET_DISK_MapHandle
  * Map a file into memory
  * @param h open file handle
  * @param m handle to the new mapping
- * @param access access specification, GNUNET_DISK_MAP_xxx
+ * @param access access specification, GNUNET_DISK_MAP_TYPE_xxx
  * @param len size of the mapping
  * @return pointer to the mapped memory region, NULL on failure
  */
 void *
 GNUNET_DISK_file_map (const struct GNUNET_DISK_FileHandle *h, struct GNUNET_DISK_MapHandle **m,
-    int access, size_t len)
+		      enum GNUNET_DISK_MapType access, size_t len)
 {
   if (h == NULL)
     {
@@ -1381,17 +1383,18 @@ GNUNET_DISK_file_map (const struct GNUNET_DISK_FileHandle *h, struct GNUNET_DISK
   DWORD mapAccess, protect;
   void *ret;
 
-  if (access & GNUNET_DISK_MAP_READ && access & GNUNET_DISK_MAP_WRITE)
+  if ((access & GNUNET_DISK_MAP_TYPE_READ) && 
+      (access & GNUNET_DISK_MAP_TYPE_WRITE))
     {
       protect = PAGE_READWRITE;
       mapAccess = FILE_MAP_ALL_ACCESS;
     }
-  else if (access & GNUNET_DISK_MAP_READ)
+  else if (access & GNUNET_DISK_MAP_TYPE_READ)
     {
       protect = PAGE_READONLY;
       mapAccess = FILE_MAP_READ;
     }
-  else if (access & GNUNET_DISK_MAP_WRITE)
+  else if (access & GNUNET_DISK_MAP_TYPE_WRITE)
     {
       protect = PAGE_READWRITE;
       mapAccess = FILE_MAP_WRITE;
@@ -1424,9 +1427,9 @@ GNUNET_DISK_file_map (const struct GNUNET_DISK_FileHandle *h, struct GNUNET_DISK
   int prot;
 
   prot = 0;
-  if (access & GNUNET_DISK_MAP_READ)
+  if (access & GNUNET_DISK_MAP_TYPE_READ)
     prot = PROT_READ;
-  if (access & GNUNET_DISK_MAP_WRITE)
+  if (access & GNUNET_DISK_MAP_TYPE_WRITE)
     prot |= PROT_WRITE;
   *m = GNUNET_malloc (sizeof (struct GNUNET_DISK_MapHandle));
   (*m)->addr = mmap (NULL, len, prot, MAP_SHARED, h->fd, 0);
diff --git a/src/util/strings.c b/src/util/strings.c
index be0e6c1f0..13c0b6a58 100644
--- a/src/util/strings.c
+++ b/src/util/strings.c
@@ -45,12 +45,18 @@
  * used to parse the buffer back into individual
  * strings.
  *
+ * @param buffer the buffer to fill with strings, can
+ *               be NULL in which case only the necessary
+ *               amount of space will be calculated
+ * @param size number of bytes available in buffer
+ * @param count number of strings that follow
+ * @param ... count 0-terminated strings to copy to buffer
  * @return number of bytes written to the buffer
  *         (or number of bytes that would have been written)
  */
 unsigned int
 GNUNET_STRINGS_buffer_fill (char *buffer,
-                            unsigned int size, unsigned int count, ...)
+                            size_t size, unsigned int count, ...)
 {
   unsigned int needed;
   unsigned int slen;
@@ -91,7 +97,7 @@ GNUNET_STRINGS_buffer_fill (char *buffer,
  */
 unsigned int
 GNUNET_STRINGS_buffer_tokenize (const char *buffer,
-                                unsigned int size, unsigned int count, ...)
+                                size_t size, unsigned int count, ...)
 {
   unsigned int start;
   unsigned int needed;
@@ -122,6 +128,9 @@ GNUNET_STRINGS_buffer_tokenize (const char *buffer,
 
 /**
  * Convert a given filesize into a fancy human-readable format.
+ *
+ * @param size number of bytes
+ * @return fancy representation of the size (possibly rounded) for humans
  */
 char *
 GNUNET_STRINGS_byte_size_fancy (unsigned long long size)