better comments

43 files changed, 245 insertions, 144 deletions

diff --git a/src/datastore/perf_plugin_datastore.c b/src/datastore/perf_plugin_datastore.c
index 1a3f890d9..9d2b1cc6c 100644
--- a/src/datastore/perf_plugin_datastore.c
+++ b/src/datastore/perf_plugin_datastore.c
@@ -192,6 +192,7 @@ iterateDummy (void *cls,
  * down.  Unloads our datastore plugin.
  *
  * @param api api to unload
+ * @param cfg configuration to use
  */
 static void
 unload_plugin (struct GNUNET_DATASTORE_PluginFunctions * api,
diff --git a/src/fs/fs_file_information.c b/src/fs/fs_file_information.c
index 5afdc392f..c20af5ea6 100644
--- a/src/fs/fs_file_information.c
+++ b/src/fs/fs_file_information.c
@@ -37,6 +37,8 @@
 /**
  * Create a temporary file on disk to store the current
  * state of "fi" in.
+ *
+ * @param fi file information to sync with disk
  */
 void
 GNUNET_FS_file_information_sync (struct GNUNET_FS_FileInformation * fi)
diff --git a/src/include/gnunet_client_lib.h b/src/include/gnunet_client_lib.h
index 17f17ab50..20842de5c 100644
--- a/src/include/gnunet_client_lib.h
+++ b/src/include/gnunet_client_lib.h
@@ -101,7 +101,7 @@ void GNUNET_CLIENT_receive (struct GNUNET_CLIENT_Connection *sock,
  * are free in the transmission buffer.  May call the notify
  * method immediately if enough space is available.
  *
- * @param client connection to the service
+ * @param sock connection to the service
  * @param size number of bytes to send
  * @param timeout after how long should we give up (and call
  *        notify with buf NULL and size 0)?
diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h
index 402674f48..df601ac19 100644
--- a/src/include/gnunet_common.h
+++ b/src/include/gnunet_common.h
@@ -181,13 +181,13 @@ GNUNET_log_skip (unsigned int n, int check_reset);
 /**
  * Setup logging.
  *
- * @param component default component to use
+ * @param comp default component to use
  * @param loglevel what types of messages should be logged
  * @param logfile change logging to logfile (use NULL to keep stderr)
  * @return GNUNET_OK on success, GNUNET_SYSERR if logfile could not be opened
  */
 int
-GNUNET_log_setup (const char *component,
+GNUNET_log_setup (const char *comp,
                   const char *loglevel, const char *logfile);
 
 /**
diff --git a/src/include/gnunet_configuration_lib.h b/src/include/gnunet_configuration_lib.h
index 8e2f8e6d9..f05d29421 100644
--- a/src/include/gnunet_configuration_lib.h
+++ b/src/include/gnunet_configuration_lib.h
@@ -55,11 +55,11 @@ struct GNUNET_CONFIGURATION_Handle *GNUNET_CONFIGURATION_create (void);
 /**
  * Duplicate an existing configuration object.
  *
- * @param c configuration to duplicate
+ * @param cfg configuration to duplicate
  * @return duplicate configuration
  */
 struct GNUNET_CONFIGURATION_Handle *
-GNUNET_CONFIGURATION_dup (const struct GNUNET_CONFIGURATION_Handle *c);
+GNUNET_CONFIGURATION_dup (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
 /**
diff --git a/src/include/gnunet_container_lib.h b/src/include/gnunet_container_lib.h
index ec190fdc6..b9ce80d95 100644
--- a/src/include/gnunet_container_lib.h
+++ b/src/include/gnunet_container_lib.h
@@ -217,13 +217,13 @@ struct GNUNET_CONTAINER_MetaData *GNUNET_CONTAINER_meta_data_create (void);
 /**
  * Duplicate a MetaData token.
  * 
- * @param meta what to duplicate
+ * @param md what to duplicate
  * @return duplicate meta-data container
  */
 struct GNUNET_CONTAINER_MetaData *GNUNET_CONTAINER_meta_data_duplicate (const
                                                                         struct
                                                                         GNUNET_CONTAINER_MetaData
-                                                                        *meta);
+                                                                        *md);
 
 /**
  * Free meta data.
@@ -261,6 +261,7 @@ int GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
 /**
  * Remove an item.
  *
+ * @param md metadata to manipulate
  * @param type type of the item to remove
  * @param data specific value to remove, NULL to remove all
  *        entries of the given type
@@ -373,7 +374,7 @@ enum GNUNET_CONTAINER_MetaDataSerializationOptions
  *
  * @param md metadata to serialize
  * @param target where to write the serialized metadata
- * @param size maximum number of bytes available
+ * @param max maximum number of bytes available
  * @param opt is it ok to just write SOME of the
  *        meta-data to match the size constraint,
  *        possibly discarding some data?
@@ -384,7 +385,7 @@ enum GNUNET_CONTAINER_MetaDataSerializationOptions
 ssize_t GNUNET_CONTAINER_meta_data_serialize (const struct
                                               GNUNET_CONTAINER_MetaData *md,
                                               char *target, 
-                                              size_t size,
+                                              size_t max,
                                               enum
                                           GNUNET_CONTAINER_MetaDataSerializationOptions
                                           opt);
@@ -958,7 +959,7 @@ void GNUNET_CONTAINER_slist_clear (struct GNUNET_CONTAINER_SList *l);
  * Check if a list contains a certain element
  * @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, const void *buf, size_t len);
 
diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index 9b795cc75..76d28ad57 100644
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -228,8 +228,7 @@ uint32_t GNUNET_CRYPTO_random_u32 (enum GNUNET_CRYPTO_Quality mode,
 
 
 /**
- * Random on unsigned 64-bit values.  We break them down into signed
- * 32-bit values and reassemble the 64-bit random value bit-wise.
+ * Random on unsigned 64-bit values. 
  *
  * @param mode desired quality of the random number
  * @param max value returned will be in range [0,max) (exclusive)
@@ -278,7 +277,7 @@ int GNUNET_CRYPTO_aes_check_session_key (const struct
  * @param sessionkey the key used to encrypt
  * @param iv the initialization vector to use, use INITVALUE
  *        for streams.
- * @returns the size of the encrypted block, -1 for errors
+ * @return the size of the encrypted block, -1 for errors
  */
 ssize_t GNUNET_CRYPTO_aes_encrypt (const void *block,
                                    size_t len,
@@ -307,10 +306,10 @@ ssize_t GNUNET_CRYPTO_aes_decrypt (const void *block,
 
 
 /**
- * Convert GNUNET_CRYPTO_hash to ASCII encoding.
- * @param block the GNUNET_CRYPTO_hash code
+ * Convert hash to ASCII encoding.
+ * @param block the hash code
  * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
- *  safely cast to char*, a '\0' termination is set).
+ *  safely cast to char*, a '\\0' termination is set).
  */
 void GNUNET_CRYPTO_hash_to_enc (const GNUNET_HashCode * block,
                                 struct GNUNET_CRYPTO_HashAsciiEncoded
@@ -515,11 +514,11 @@ 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
+ * @param hc "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);
+  *GNUNET_CRYPTO_rsa_key_create_from_hash (const GNUNET_HashCode * hc);
 
 
 /**
@@ -550,7 +549,7 @@ void GNUNET_CRYPTO_rsa_key_get_public (const struct
  * @param size the size of block
  * @param publicKey the encoded public key used to encrypt
  * @param target where to store the encrypted block
- * @returns GNUNET_SYSERR on error, GNUNET_OK if ok
+ * @return GNUNET_SYSERR on error, GNUNET_OK if ok
  */
 int GNUNET_CRYPTO_rsa_encrypt (const void *block,
                                size_t size,
@@ -566,14 +565,14 @@ int GNUNET_CRYPTO_rsa_encrypt (const void *block,
  * @param key the key to use
  * @param block the data to decrypt, encoded as returned by encrypt, not consumed
  * @param result pointer to a location where the result can be stored
- * @param size how many bytes of a result are expected? Must be exact.
- * @returns the size of the decrypted block (that is, size) or -1 on error
+ * @param max how many bytes of a result are expected? Must be exact.
+ * @return the size of the decrypted block (that is, size) or -1 on error
  */
 ssize_t GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
                                    const struct GNUNET_CRYPTO_RsaEncryptedData
                                    *block,
                                    void *result, 
-                                   size_t size);
+                                   size_t max);
 
 
 /**
@@ -581,13 +580,13 @@ ssize_t GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *key
  *
  * @param key private key to use for the signing
  * @param purpose what to sign (size, purpose)
- * @param result where to write the signature
+ * @param sig where to write the signature
  * @return GNUNET_SYSERR on error, GNUNET_OK on success
  */
 int GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
                             const struct GNUNET_CRYPTO_RsaSignaturePurpose
                             *purpose,
-                            struct GNUNET_CRYPTO_RsaSignature *result);
+                            struct GNUNET_CRYPTO_RsaSignature *sig);
 
 
 /**
@@ -598,7 +597,7 @@ int GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
  * @param validate block to validate (size, purpose, data)
  * @param sig signature that is being validated
  * @param publicKey public key of the signer
- * @returns GNUNET_OK if ok, GNUNET_SYSERR if invalid
+ * @return GNUNET_OK if ok, GNUNET_SYSERR if invalid
  */
 int GNUNET_CRYPTO_rsa_verify (uint32_t purpose,
                               const struct GNUNET_CRYPTO_RsaSignaturePurpose
diff --git a/src/include/gnunet_dht_service.h b/src/include/gnunet_dht_service.h
index 0dab0bcbc..4bf3ce15b 100644
--- a/src/include/gnunet_dht_service.h
+++ b/src/include/gnunet_dht_service.h
@@ -93,6 +93,7 @@ typedef void (*GNUNET_DHT_Iterator)(void *cls,
 /**
  * Perform an asynchronous GET operation on the DHT identified.
  *
+ * @param h handle to the DHT service
  * @param type expected type of the response object
  * @param key the key to look up
  * @param iter function to call on each result
diff --git a/src/include/gnunet_fs_service.h b/src/include/gnunet_fs_service.h
index ae1b46a89..5449f6324 100644
--- a/src/include/gnunet_fs_service.h
+++ b/src/include/gnunet_fs_service.h
@@ -198,7 +198,7 @@ GNUNET_FS_uri_loc_get_expiration (const struct GNUNET_FS_Uri *uri);
 /**
  * Construct a location URI (this peer will be used for the location).
  *
- * @param baseURI content offered by the sender
+ * @param baseUri content offered by the sender
  * @param cfg configuration information (used to find our hostkey)
  * @param expiration_time how long will the content be offered?
  * @return the location URI, NULL on error
@@ -1552,10 +1552,10 @@ GNUNET_FS_file_information_get_id (struct GNUNET_FS_FileInformation *s);
  * file information data should already call "sync" internally,
  * so this function is likely not useful for clients.
  * 
- * @param s the struct to sync
+ * @param fi the struct to sync
  */
 void
-GNUNET_FS_file_information_sync (struct GNUNET_FS_FileInformation *s);
+GNUNET_FS_file_information_sync (struct GNUNET_FS_FileInformation *f);
 
 
 /**
@@ -1809,14 +1809,14 @@ GNUNET_FS_file_information_create_empty_directory (void *client_info,
  * "GNUNET_FS_publish_start" already.
  *
  * @param dir the directory
- * @param end the entry to add; the entry must not have been
+ * @param ent the entry to add; the entry must not have been
  *            added to any other directory at this point and 
  *            must not include "dir" in its structure
  * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
 GNUNET_FS_file_information_add (struct GNUNET_FS_FileInformation *dir,
-                                struct GNUNET_FS_FileInformation *end);
+                                struct GNUNET_FS_FileInformation *ent);
 
 
 /**
@@ -1926,7 +1926,7 @@ typedef void (*GNUNET_FS_PublishContinuation)(void *cls,
  * Publish a KBlock on GNUnet.
  *
  * @param h handle to the file sharing subsystem
- * @param keywords keywords to use
+ * @param ksk_uri keywords to use
  * @param meta metadata to use
  * @param uri URI to refer to in the KBlock
  * @param expirationTime when the KBlock expires
@@ -1937,7 +1937,7 @@ typedef void (*GNUNET_FS_PublishContinuation)(void *cls,
  */
 void
 GNUNET_FS_publish_ksk (struct GNUNET_FS_Handle *h,
-                       struct GNUNET_FS_Uri *keywords,
+                       struct GNUNET_FS_Uri *ksk_uri,
                        struct GNUNET_CONTAINER_MetaData *meta,
                        struct GNUNET_FS_Uri *uri,
                        struct GNUNET_TIME_Absolute expirationTime,
@@ -2258,11 +2258,11 @@ GNUNET_FS_file_download_start (struct GNUNET_FS_Handle *h,
 /**
  * Stop a download (aborts if download is incomplete).
  *
- * @param rm handle for the download
+ * @param dc handle for the download
  * @param do_delete delete files of incomplete downloads
  */
 void
-GNUNET_FS_file_download_stop (struct GNUNET_FS_DownloadContext *rm,
+GNUNET_FS_file_download_stop (struct GNUNET_FS_DownloadContext *dc,
                               int do_delete);
 
 
@@ -2439,14 +2439,14 @@ GNUNET_FS_directory_builder_add (struct GNUNET_FS_DirectoryBuilder *bld,
  * in-memory.
  *
  * @param bld directory to finish
- * @param size set to the number of bytes needed
- * @param data set to the encoded directory
+ * @param rsize set to the number of bytes needed
+ * @param rdata set to the encoded directory
  * @return GNUNET_OK on success
  */
 int
 GNUNET_FS_directory_builder_finish (struct GNUNET_FS_DirectoryBuilder *bld,
-                                    size_t *size,
-                                    void **data);
+                                    size_t *rsize,
+                                    void **rdata);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index 44525e2f2..d5f3d1198 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -186,14 +186,14 @@ struct GNUNET_GETOPT_CommandLineOption
 /**
  * Parse the command line.
  *
- * @param binaryName name of the binary / application with options
+ * @param binaryOptions Name of application with option summary
  * @param allOptions defined options and handlers
  * @param argc number of arguments
  * @param argv actual arguments
  * @return index into argv with first non-option
  *   argument, or GNUNET_SYSERR on error
  */
-int GNUNET_GETOPT_run (const char *binaryName,
+int GNUNET_GETOPT_run (const char *binaryOptions,
                        const struct GNUNET_GETOPT_CommandLineOption
                        *allOptions, unsigned int argc, char *const *argv);
 
diff --git a/src/include/gnunet_network_lib.h b/src/include/gnunet_network_lib.h
index d966c3afe..e4ba55854 100644
--- a/src/include/gnunet_network_lib.h
+++ b/src/include/gnunet_network_lib.h
@@ -100,11 +100,12 @@ int GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc);
  *
  * @param desc socket to connect
  * @param address peer address
- * @param length of address
+ * @param address_len of address
  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
  */
 int GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc,
-                       const struct sockaddr *address, socklen_t address_len);
+                                   const struct sockaddr *address, 
+                                   socklen_t address_len);
 
 
 /**
@@ -262,7 +263,7 @@ void GNUNET_NETWORK_fdset_copy(struct GNUNET_NETWORK_FDSet *to,
  * Copy a native fd set
  * @param to destination
  * @param from native source set
- * @param the biggest socket number in from + 1
+ * @param nfds the biggest socket number in from + 1
  */
 void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, 
                                        const fd_set *from,
diff --git a/src/include/gnunet_pseudonym_lib.h b/src/include/gnunet_pseudonym_lib.h
index ced9bf387..ba240941b 100644
--- a/src/include/gnunet_pseudonym_lib.h
+++ b/src/include/gnunet_pseudonym_lib.h
@@ -55,20 +55,25 @@ typedef int (*GNUNET_PSEUDONYM_Iterator) (void *cls,
 /**
  * Change the ranking of a pseudonym.
  *
- * @param pseudonym id of the pseudonym
+ * @param cfg overall configuration
+ * @param nsid id of the pseudonym
  * @param delta by how much should the rating be changed?
  * @return new rating of the namespace
  */
 int GNUNET_PSEUDONYM_rank (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                           const GNUNET_HashCode * pseudonym, int delta);
+                           const GNUNET_HashCode *nsid, int delta);
 
 /**
  * Add a pseudonym to the set of known pseudonyms.
+ * For all pseudonym advertisements that we discover
+ * FS should automatically call this function.
  *
- * @param pseudonym the pseudonym's identifier
+ * @param cfg overall configuration
+ * @param id the pseudonym identifier
+ * @param meta metadata for the pseudonym
  */
 void GNUNET_PSEUDONYM_add (const struct GNUNET_CONFIGURATION_Handle *cfg,
-                           const GNUNET_HashCode * pseudo,
+                           const GNUNET_HashCode *id,
                            const struct GNUNET_CONTAINER_MetaData *meta);
 
 
diff --git a/src/include/gnunet_scheduler_lib.h b/src/include/gnunet_scheduler_lib.h
index db94f05ab..621e57fcf 100644
--- a/src/include/gnunet_scheduler_lib.h
+++ b/src/include/gnunet_scheduler_lib.h
@@ -482,7 +482,6 @@ GNUNET_SCHEDULER_add_write_file (struct GNUNET_SCHEDULER_Handle *sched,
  *        are satisfied).  Use GNUNET_SCHEDULER_NO_TASK to not have any dependency
  *        on completion of other tasks.
  * @param delay how long should we wait? Use GNUNET_TIME_UNIT_FOREVER_REL for "forever"
- * @param nfds highest-numbered file descriptor in any of the two sets plus one
  * @param rs set of file descriptors we want to read (can be NULL)
  * @param ws set of file descriptors we want to write (can be NULL)
  * @param main main function of the task
@@ -497,7 +496,8 @@ GNUNET_SCHEDULER_add_select (struct GNUNET_SCHEDULER_Handle *sched,
                              GNUNET_SCHEDULER_TaskIdentifier
                              prerequisite_task,
                              struct GNUNET_TIME_Relative delay,
-                             const struct GNUNET_NETWORK_FDSet * rs, const struct GNUNET_NETWORK_FDSet * ws,
+                             const struct GNUNET_NETWORK_FDSet * rs,
+                             const struct GNUNET_NETWORK_FDSet * ws,
                              GNUNET_SCHEDULER_Task main, void *cls);
 
 #if 0                           /* keep Emacsens' auto-indent happy */
diff --git a/src/include/gnunet_server_lib.h b/src/include/gnunet_server_lib.h
index 135b1f196..570985d16 100644
--- a/src/include/gnunet_server_lib.h
+++ b/src/include/gnunet_server_lib.h
@@ -329,7 +329,7 @@ typedef void (*GNUNET_SERVER_DestroyCallback) (void *cls);
  * @param server the server to use
  * @param chandle opaque handle for the connection
  * @param creceive receive function for the connection
- * @param creceive_cancel cancel receive function for the connection
+ * @param ccancel cancel receive function for the connection
  * @param cnotify transmit notification function for the connection
  * @param cnotify_cancel transmit notification cancellation function for the connection
  * @param ccheck function to test if the connection is still up
diff --git a/src/include/gnunet_service_lib.h b/src/include/gnunet_service_lib.h
index 4d0eefb98..0c69d297c 100644
--- a/src/include/gnunet_service_lib.h
+++ b/src/include/gnunet_service_lib.h
@@ -123,9 +123,9 @@ struct GNUNET_SERVER_Handle *GNUNET_SERVICE_get_server (struct
 /**
  * Stop a service that was started with "GNUNET_SERVICE_start".
  *
- * @param ctx the service context returned from the start function
+ * @param sctx the service context returned from the start function
  */
-void GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *ctx);
+void GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
 
 
 #if 0                           /* keep Emacsens' auto-indent happy */
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h
index 604610774..8bf295567 100644
--- a/src/include/gnunet_transport_service.h
+++ b/src/include/gnunet_transport_service.h
@@ -106,7 +106,7 @@ typedef void
  * @param cls closure for the callbacks
  * @param rec receive function to call
  * @param nc function to call on connect events
- * @param dc function to call on disconnect events
+ * @param nd function to call on disconnect events
  */
 struct GNUNET_TRANSPORT_Handle *GNUNET_TRANSPORT_connect (struct
                                                           GNUNET_SCHEDULER_Handle
diff --git a/src/peerinfo/gnunet-service-peerinfo.c b/src/peerinfo/gnunet-service-peerinfo.c
index 281779897..3608dab84 100644
--- a/src/peerinfo/gnunet-service-peerinfo.c
+++ b/src/peerinfo/gnunet-service-peerinfo.c
@@ -104,6 +104,10 @@ static char *trustDirectory;
  * Address iterator that causes expired entries to be discarded.
  *
  * @param cls pointer to the current time
+ * @param tname name of the transport
+ * @param expiration expiration time for the address
+ * @param addr the address
+ * @param addrlen length of addr in bytes
  * @return GNUNET_NO if expiration smaller than the current time
  */
 static int
@@ -176,7 +180,6 @@ lookup_host_entry (const struct GNUNET_PeerIdentity *id)
  * Add a host to the list.
  *
  * @param identity the identity of the host
- * @param protocol the protocol for the host
  */
 static void
 add_host_to_known_hosts (const struct GNUNET_PeerIdentity *identity)
@@ -398,7 +401,9 @@ bind_address (const struct GNUNET_PeerIdentity *peer,
  * argument or for all known hosts and change their trust values by
  * the given delta.
  *
- * @param only NULL to hit all hosts
+ * @param only NULL to hit all hosts, otherwise specifies a particular target
+ * @param trust_change how much should the trust be changed
+ * @param client who is making the request (and will thus receive our confirmation)
  */
 static void
 send_to_each_host (const struct GNUNET_PeerIdentity *only,
diff --git a/src/peerinfo/peerinfo_api.c b/src/peerinfo/peerinfo_api.c
index 57197798b..14efa1708 100644
--- a/src/peerinfo/peerinfo_api.c
+++ b/src/peerinfo/peerinfo_api.c
@@ -76,7 +76,6 @@ copy_and_free (void *cls, size_t size, void *buf)
  * @param sched scheduler to use
  * @param peer identity of the peer
  * @param hello the verified (!) HELLO message
- * @param expiration when the HELLO will expire
  */
 void
 GNUNET_PEERINFO_add_peer (const struct GNUNET_CONFIGURATION_Handle *cfg,
diff --git a/src/statistics/gnunet-statistics.c b/src/statistics/gnunet-statistics.c
index fe75f93aa..bea9ca0ca 100644
--- a/src/statistics/gnunet-statistics.c
+++ b/src/statistics/gnunet-statistics.c
@@ -65,11 +65,11 @@ static int persistent;
 static int
 printer (void *cls,
          const char *subsystem,
-         const char *sname, unsigned long long value, int is_persistent)
+         const char *name, unsigned long long value, int is_persistent)
 {
   FPRINTF (stdout,
            "%s%-20s %-40s: %16llu\n",
-           is_persistent ? "!" : " ", subsystem, _(sname), value);
+           is_persistent ? "!" : " ", subsystem, _(name), value);
   return GNUNET_OK;
 }
 
diff --git a/src/statistics/statistics_api.c b/src/statistics/statistics_api.c
index 26e2425e6..335cd4165 100644
--- a/src/statistics/statistics_api.c
+++ b/src/statistics/statistics_api.c
@@ -201,6 +201,7 @@ free_action_item (struct ActionItem *ai)
 /**
  * Get handle for the statistics service.
  *
+ * @param sched scheduler to use
  * @param subsystem name of subsystem using the service
  * @param cfg services configuration in use
  * @return handle to use
diff --git a/src/topology/gnunet-daemon-topology.c b/src/topology/gnunet-daemon-topology.c
index 466e06961..6dc492a56 100644
--- a/src/topology/gnunet-daemon-topology.c
+++ b/src/topology/gnunet-daemon-topology.c
@@ -250,7 +250,8 @@ ready_callback (void *cls,
 /**
  * Try to connect to the specified peer.
  *
- * @param pos NULL if not in friend list yet
+ * @param peer who we should try to connect to
+ * @param pos entry in our friend list; NULL if not in friend list yet
  */
 static void
 attempt_connect (const struct GNUNET_PeerIdentity *peer,
@@ -475,7 +476,12 @@ schedule_peer_search ()
 /**
  * Iterator called on each address.
  *
- * @param cls flag that we will set if we see any addresses.
+ * @param cls flag that we will set if we see any addresses
+ * @param tname name of the transport
+ * @param expiration when will the given address expire
+ * @param addr the address of the peer
+ * @param addrlen number of bytes in addr
+ * @return GNUNET_SYSERR always, to terminate iteration
  */
 static int
 address_iterator (void *cls,
@@ -840,7 +846,7 @@ read_friends_file (const struct GNUNET_CONFIGURATION_Handle *cfg)
  * received.
  *
  * @param cls closure
- * @param peer the other peer involved (sender or receiver, NULL
+ * @param other the other peer involved (sender or receiver, NULL
  *        for loopback messages where we are both sender and receiver)
  * @param message the actual HELLO message
  * @return GNUNET_OK to keep the connection open,
@@ -862,6 +868,11 @@ handle_encrypted_hello (void *cls,
 /**
  * Peerinfo calls this function to let us know about a
  * possible peer that we might want to connect to.
+ *
+ * @param cls unused
+ * @param peer NULL for the end of the list, otherwise a peer identity
+ * @param hello a HELLO for a peer, or NULL
+ * @param trust how much do we trust the given peer?
  */
 static void
 gather_hello_callback (void *cls,
@@ -882,6 +893,7 @@ gather_hello_callback (void *cls,
 /**
  * Function to fill send buffer with HELLO.
  *
+ * @param cls unused
  * @param receiver the receiver of the message
  * @param position is the reference to the
  *        first unused position in the buffer where GNUnet is building
diff --git a/src/transport/gnunet-service-transport.c b/src/transport/gnunet-service-transport.c
index 192ebf98f..6803e3179 100644
--- a/src/transport/gnunet-service-transport.c
+++ b/src/transport/gnunet-service-transport.c
@@ -2066,6 +2066,7 @@ setup_new_neighbour (const struct GNUNET_PeerIdentity *peer)
  * reducing the rate at which they read from the socket
  * and generally forward to our receive callback.
  *
+ * @param cls the "struct TransportPlugin *" we gave to the plugin
  * @param plugin_context value to pass to this plugin
  *        to respond to the given peer (use is optional,
  *        but may speed up processing)
diff --git a/src/transport/plugin_transport_http.c b/src/transport/plugin_transport_http.c
index c2f531b54..5fd875623 100644
--- a/src/transport/plugin_transport_http.c
+++ b/src/transport/plugin_transport_http.c
@@ -1231,6 +1231,7 @@ create_curl_get (HTTPSession * httpSession)
  *
  * @param hello the hello-Message for the target node
  * @param tsessionPtr the session handle that is set
+ * @param may_reuse are we allowed to re-use an existing connection?
  * @return GNUNET_OK on success, GNUNET_SYSERR if the operation failed
  */
 static int
@@ -1458,6 +1459,7 @@ httpTestWouldTry (GNUNET_TSession * tsession, const unsigned int size,
  * @param tsession the GNUNET_MessageHello identifying the remote node
  * @param msg the message
  * @param size the size of the message
+ * @param important is this message so important that usual restrictions do not apply?
  * @return GNUNET_SYSERR on error, GNUNET_OK on success, GNUNET_NO if queue is full
  */
 static int
diff --git a/src/transport/plugin_transport_smtp.c b/src/transport/plugin_transport_smtp.c
index b93b16fb7..ec54d3f22 100644
--- a/src/transport/plugin_transport_smtp.c
+++ b/src/transport/plugin_transport_smtp.c
@@ -516,8 +516,9 @@ get_message (void **buf, int *len, void *cls)
  * Send a message to the specified remote node.
  *
  * @param tsession the GNUNET_MessageHello identifying the remote node
- * @param message what to send
+ * @param msg what to send
  * @param size the size of the message
+ * @param important is this message important enough to override typical limits?
  * @return GNUNET_SYSERR on error, GNUNET_OK on success
  */
 static int
@@ -689,8 +690,9 @@ api_send (GNUNET_TSession * tsession,
 
 /**
  * Establish a connection to a remote node.
- * @param helo the hello-Message for the target node
+ * @param hello the hello-Message for the target node
  * @param tsessionPtr the session handle that is to be set
+ * @param may_reuse can we re-use an existing connection?
  * @return GNUNET_OK on success, GNUNET_SYSERR if the operation failed
  */
 static int
diff --git a/src/transport/plugin_transport_tcp.c b/src/transport/plugin_transport_tcp.c
index 8e5f5dcef..89c64021e 100644
--- a/src/transport/plugin_transport_tcp.c
+++ b/src/transport/plugin_transport_tcp.c
@@ -1059,13 +1059,14 @@ session_try_connect (void *cls,
  * @param target who should receive this message
  * @param priority how important is the message
  * @param msg the message to transmit
+ * @param timeout when should we time out (give up) if we can not transmit?
  * @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 plugin_context that should be used next time for
- *         sending messages to the specified peer
+  *         sending messages to the specified peer
  */
 static void *
 tcp_plugin_send (void *cls,
@@ -1252,7 +1253,7 @@ append_port (void *cls, const char *hostname)
  * format.
  *
  * @param cls closure
- * @param name name of the transport that generated the address
+ * @param type name of the transport that generated the address
  * @param addr one of the addresses of the host, NULL for the last address
  *        the specific address format depends on the transport
  * @param addrlen length of the address
@@ -1353,7 +1354,7 @@ update_quota (struct Session *session, int force)
  * calls to stay below the quota (in terms of incoming data).
  *
  * @param cls closure
- * @param peer the peer for whom the quota is given
+ * @param target the peer for whom the quota is given
  * @param quota_in quota for receiving/sending data in bytes per ms
  */
 static void
@@ -1581,8 +1582,8 @@ handle_tcp_ping (void *cls,
 /**
  * Handle PONG-message.
  *
- * @param plugin handle for this plugin
- * @param sender claimed sender of the PONG
+ * @param cls handle for this plugin
+ * @param client from where did we receive the PONG
  * @param message the actual message
  */
 static void
diff --git a/src/transport/plugin_transport_template.c b/src/transport/plugin_transport_template.c
index 6307092fc..95fd2de5f 100644
--- a/src/transport/plugin_transport_template.c
+++ b/src/transport/plugin_transport_template.c
@@ -171,6 +171,7 @@ template_plugin_validate (void *cls,
  * @param target who should receive this message
  * @param priority how important is the message
  * @param msg the message to transmit
+ * @param timeout when should we time out 
  * @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
@@ -226,7 +227,7 @@ template_plugin_cancel (void *cls,
  * format.
  *
  * @param cls closure
- * @param name name of the transport that generated the address
+ * @param type name of the transport that generated the address
  * @param addr one of the addresses of the host, NULL for the last address
  *        the specific address format depends on the transport
  * @param addrlen length of the address
@@ -254,7 +255,7 @@ template_plugin_address_pretty_printer (void *cls,
  * calls to stay below the quota (in terms of incoming data).
  *
  * @param cls closure
- * @param peer the peer for whom the quota is given
+ * @param target the peer for whom the quota is given
  * @param quota_in quota for receiving/sending data in bytes per ms
  */
 static void
diff --git a/src/transport/plugin_transport_udp.c b/src/transport/plugin_transport_udp.c
index 0194a1667..624ca0933 100644
--- a/src/transport/plugin_transport_udp.c
+++ b/src/transport/plugin_transport_udp.c
@@ -151,6 +151,7 @@ select_close_handler (void *ch_cls,
  *
  * @param hello the hello-Message for the target node
  * @param tsessionPtr the session handle that is to be set
+ * @param may_reuse are we allowed to re-use an existing connection (ignored for UDP)
  * @return GNUNET_OK on success, GNUNET_SYSERR if the operation failed
  */
 static int
@@ -305,6 +306,7 @@ udp_create_socket ()
  * @param tsession the GNUNET_MessageHello identifying the remote node
  * @param message what to send
  * @param size the size of the message
+ * @param important is this message "important" to override typical transmit limits?
  * @return GNUNET_SYSERR on error, GNUNET_OK on success
  */
 static int
diff --git a/src/transport/transport_api.c b/src/transport/transport_api.c
index 9a7068e42..f6ba793ce 100644
--- a/src/transport/transport_api.c
+++ b/src/transport/transport_api.c
@@ -598,6 +598,7 @@ peer_transmit_timeout (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc)
  * Queue control request for transmission to the transport
  * service.
  *
+ * @param h handle to the transport service
  * @param size number of bytes to be transmitted
  * @param at_head request must be added to the head of the queue
  *        (otherwise request will be appended)
@@ -1446,7 +1447,7 @@ add_neighbour (struct GNUNET_TRANSPORT_Handle *h,
  * @param cls closure for the callbacks
  * @param rec receive function to call
  * @param nc function to call on connect events
- * @param dc function to call on disconnect events
+ * @param nd function to call on disconnect events
  */
 struct GNUNET_TRANSPORT_Handle *
 GNUNET_TRANSPORT_connect (struct GNUNET_SCHEDULER_Handle *sched,
diff --git a/src/upnp/upnp.h b/src/upnp/upnp.h
index 1f99c5352..a77755a3c 100644
--- a/src/upnp/upnp.h
+++ b/src/upnp/upnp.h
@@ -61,12 +61,10 @@ const char *gaim_upnp_get_public_ip (void);
  * this gaim client. Essentially, this function takes care of the port
  * forwarding so things like file transfers can work behind NAT firewalls
  *
+ * @param cfg configuration to use
+ * @param do_add TRUE/GNUNET_YES to add, FALSE/GNUNET_NO to remove
  * @param portmap The port to map to this client
  * @param protocol The protocol to map, either "TCP" or "UDP"
- * @param do_add TRUE/GNUNET_YES to add, FALSE/GNUNET_NO to remove
- * @param cb an optional callback function to be notified when the mapping
- *           addition is complete
- * @param cb_data Extra data to be passed to the callback
  */
 int gaim_upnp_change_port_mapping (struct GNUNET_CONFIGURATION_Handle *cfg,
                                    int do_add,
diff --git a/src/util/common_logging.c b/src/util/common_logging.c
index 0ee4edbe2..96cfcd85c 100644
--- a/src/util/common_logging.c
+++ b/src/util/common_logging.c
@@ -438,14 +438,14 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind)
  * This is one of the very few calls in the entire API that is
  * NOT reentrant!
  *
- * @param pid the peer identity
+ * @param hc the hash code
  * @return string form; will be overwritten by next call to GNUNET_h2s.
  */
 const char *
-GNUNET_h2s (const GNUNET_HashCode *pid)
+GNUNET_h2s (const GNUNET_HashCode *hc)
 {
   static struct GNUNET_CRYPTO_HashAsciiEncoded ret;
-  GNUNET_CRYPTO_hash_to_enc (pid, &ret);
+  GNUNET_CRYPTO_hash_to_enc (hc, &ret);
   ret.encoding[8] = '\0';
   return (const char *) ret.encoding;
 }
diff --git a/src/util/container_bloomfilter.c b/src/util/container_bloomfilter.c
index 5e69fe8ab..612bad92f 100644
--- a/src/util/container_bloomfilter.c
+++ b/src/util/container_bloomfilter.c
@@ -666,14 +666,14 @@ GNUNET_CONTAINER_bloomfilter_remove (struct GNUNET_CONTAINER_BloomFilter *bf,
  *
  * @param bf the filter
  * @param iterator an iterator over all elements stored in the BF
- * @param iterator_arg argument to the iterator function
+ * @param iterator_cls argument to the iterator function
  * @param size the new size for the filter
  * @param k the new number of GNUNET_CRYPTO_hash-function to apply per element
  */
 void
 GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
                                      GNUNET_HashCodeIterator iterator,
-                                     void *iterator_arg, 
+                                     void *iterator_cls, 
                                      size_t size,
                                      unsigned int k)
 {
@@ -691,7 +691,7 @@ GNUNET_CONTAINER_bloomfilter_resize (struct GNUNET_CONTAINER_BloomFilter *bf,
   memset (bf->bitArray, 0, bf->bitArraySize);
   if (bf->filename != NULL)
     makeEmptyFile (bf->fh, bf->bitArraySize * 4);
-  while (GNUNET_YES == iterator (iterator_arg, &hc))
+  while (GNUNET_YES == iterator (iterator_cls, &hc))
     GNUNET_CONTAINER_bloomfilter_add (bf, &hc);
 }
 
diff --git a/src/util/container_meta_data.c b/src/util/container_meta_data.c
index bbe6dad3b..5ae3b15cf 100644
--- a/src/util/container_meta_data.c
+++ b/src/util/container_meta_data.c
@@ -139,6 +139,11 @@ GNUNET_CONTAINER_meta_data_insert (struct GNUNET_CONTAINER_MetaData *md,
 
 /**
  * Remove an item.
+ *
+ * @param md metadata to manipulate
+ * @param type type of the item to remove
+ * @param data specific value to remove, NULL to remove all
+ *        entries of the given type
  * @return GNUNET_OK on success, GNUNET_SYSERR if the item does not exist in md
  */
 int
@@ -170,13 +175,16 @@ GNUNET_CONTAINER_meta_data_delete (struct GNUNET_CONTAINER_MetaData *md,
 /**
  * Iterate over MD entries, excluding thumbnails.
  *
+ * @param md metadata to inspect
+ * @param iter function to call on each entry
+ * @param iter_cls closure for iterator
  * @return number of entries
  */
 int
 GNUNET_CONTAINER_meta_data_get_contents (const struct
                                          GNUNET_CONTAINER_MetaData *md,
                                          GNUNET_CONTAINER_MetaDataProcessor
-                                         iterator, void *closure)
+                                         iter, void *iter_cls)
 {
   uint32_t i;
   uint32_t sub;
@@ -187,9 +195,9 @@ GNUNET_CONTAINER_meta_data_get_contents (const struct
       if (!EXTRACTOR_isBinaryType (md->items[i].type))
         {
           if ((iterator != NULL) &&
-              (GNUNET_OK != iterator (closure,
-                                      md->items[i].type,
-                                      md->items[i].data)))
+              (GNUNET_OK != iter (iter_cls,
+                                  md->items[i].type,
+                                  md->items[i].data)))
             return GNUNET_SYSERR;
         }
       else
@@ -280,6 +288,9 @@ GNUNET_CONTAINER_meta_data_get_thumbnail (const struct
 
 /**
  * Duplicate struct GNUNET_CONTAINER_MetaData.
+ * 
+ * @param md what to duplicate
+ * @return duplicate meta-data container
  */
 struct GNUNET_CONTAINER_MetaData *
 GNUNET_CONTAINER_meta_data_duplicate (const struct GNUNET_CONTAINER_MetaData
@@ -439,7 +450,7 @@ struct MetaDataHeader
  * @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
+ * @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 written on success,
@@ -451,7 +462,7 @@ GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaData
                                       *md, char *target, size_t max,
                                       enum
                                       GNUNET_CONTAINER_MetaDataSerializationOptions
-                                      part)
+                                      opt)
 {
   struct MetaDataHeader *hdr;
   size_t size;
@@ -488,7 +499,7 @@ GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaData
         }
 
       hdr->size = htonl (size);
-      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],
                                 size - sizeof (struct MetaDataHeader));
@@ -507,7 +518,7 @@ GNUNET_CONTAINER_meta_data_serialize (const struct GNUNET_CONTAINER_MetaData
       GNUNET_free (hdr);
       hdr = NULL;
 
-      if ((part & GNUNET_CONTAINER_META_DATA_SERIALIZE_PART) == 0)
+      if ((opt & GNUNET_CONTAINER_META_DATA_SERIALIZE_PART) == 0)
         {
           return GNUNET_SYSERR; /* does not fit! */
         }
diff --git a/src/util/crypto_hash.c b/src/util/crypto_hash.c
index c3fb9a84c..60e0ec5a2 100644
--- a/src/util/crypto_hash.c
+++ b/src/util/crypto_hash.c
@@ -562,7 +562,7 @@ getValue__ (unsigned char a)
  * small number of characters.  The GNUnet encoding uses 102
  * characters plus a null terminator.
  *
- * @param block the GNUNET_CRYPTO_hash code
+ * @param block the hash code
  * @param result where to store the encoding (struct GNUNET_CRYPTO_HashAsciiEncoded can be
  *  safely cast to char*, a '\\0' termination is set).
  */
diff --git a/src/util/crypto_random.c b/src/util/crypto_random.c
index b56523a46..50af9f251 100644
--- a/src/util/crypto_random.c
+++ b/src/util/crypto_random.c
@@ -30,6 +30,10 @@
 #include <gcrypt.h>
 
 /**
+ * Produce a random value.
+ *
+ * @param mode desired quality of the random number
+ * @param i the upper limit (exclusive) for the random number
  * @return a random value in the interval [0,i[.
  */
 uint32_t
@@ -97,26 +101,31 @@ GNUNET_CRYPTO_random_permute (enum GNUNET_CRYPTO_Quality mode, unsigned int n)
 
 /**
  * Random on unsigned 64-bit values.
+ *
+ *
+ * @param mode desired quality of the random number
+ * @param max value returned will be in range [0,max) (exclusive)
+ * @return random 64-bit number
  */
 uint64_t
 GNUNET_CRYPTO_random_u64 (enum GNUNET_CRYPTO_Quality mode,
-                          uint64_t u)
+                          uint64_t max)
 {
   uint64_t ret;
 
-  GNUNET_assert (u > 0);
+  GNUNET_assert (max > 0);
   if (mode == GNUNET_CRYPTO_QUALITY_STRONG)
     {
       gcry_randomize ((unsigned char *) &ret,
                       sizeof (uint64_t),
                       GCRY_STRONG_RANDOM);
-      return ret % u;
+      return ret % max;
     }
   else
     {
-      ret = u * ((double) RANDOM () / RAND_MAX);
-      if (ret >= u)
-        ret = u - 1;
+      ret = max * ((double) RANDOM () / RAND_MAX);
+      if (ret >= max)
+        ret = max - 1;
       return ret;
     }
 }
diff --git a/src/util/crypto_rsa.c b/src/util/crypto_rsa.c
index 7bffa71ee..9da95a56e 100644
--- a/src/util/crypto_rsa.c
+++ b/src/util/crypto_rsa.c
@@ -186,15 +186,15 @@ key_from_sexp (gcry_mpi_t * array,
 
 /**
  * Extract the public key of the host.
- * @param hostkey the hostkey to extract into the result.
- * @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,
+                                  *priv,
                                   struct
                                   GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded
-                                  *result)
+                                  *pub)
 {
   gcry_mpi_t skey[2];
   size_t size;
@@ -750,15 +750,15 @@ GNUNET_CRYPTO_rsa_encrypt (const void *block,
 /**
  * Decrypt a given block with the hostkey.
  *
- * @param hostkey the hostkey with which to decrypt this block
+ * @param key the key with which to decrypt this block
  * @param block the data to decrypt, encoded as returned by encrypt
  * @param result pointer to a location where the result can be stored
  * @param max the maximum number of bits to store for the result, if
  *        the decrypted block is bigger, an error is returned
- * @returns the size of the decrypted block, -1 on error
+ * @return the size of the decrypted block, -1 on error
  */
 ssize_t
-GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *hostkey,
+GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
                            const struct GNUNET_CRYPTO_RsaEncryptedData *block,
                            void *result, 
                            size_t max)
@@ -772,7 +772,7 @@ GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *hostkey,
   unsigned char *tmp;
 
 #if EXTRA_CHECKS
-  GNUNET_assert (0 == gcry_pk_testkey (hostkey->sexp));
+  GNUNET_assert (0 == gcry_pk_testkey (key->sexp));
 #endif
   size = sizeof (struct GNUNET_CRYPTO_RsaEncryptedData);
   GNUNET_assert (0 == gcry_mpi_scan (&val,
@@ -782,7 +782,7 @@ GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *hostkey,
                  gcry_sexp_build (&data, &erroff,
                                   "(enc-val(flags)(rsa(a %m)))", val));
   gcry_mpi_release (val);
-  GNUNET_assert (0 == gcry_pk_decrypt (&resultsexp, data, hostkey->sexp));
+  GNUNET_assert (0 == gcry_pk_decrypt (&resultsexp, data, key->sexp));
   gcry_sexp_release (data);
   /* resultsexp has format "(value %m)" */
   GNUNET_assert (NULL !=
@@ -805,13 +805,13 @@ GNUNET_CRYPTO_rsa_decrypt (const struct GNUNET_CRYPTO_RsaPrivateKey *hostkey,
 /**
  * Sign a given block.
  *
- * @param hostkey private key to use for the signing
+ * @param key private key to use for the signing
  * @param purpose what to sign (size, purpose)
  * @param sig where to write the signature
  * @return GNUNET_SYSERR on error, GNUNET_OK on success
  */
 int
-GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_RsaPrivateKey *hostkey,
+GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_RsaPrivateKey *key,
                         const struct GNUNET_CRYPTO_RsaSignaturePurpose
                         *purpose, struct GNUNET_CRYPTO_RsaSignature *sig)
 {
@@ -835,7 +835,7 @@ GNUNET_CRYPTO_rsa_sign (const struct GNUNET_CRYPTO_RsaPrivateKey *hostkey,
            - 1], &hc, sizeof (GNUNET_HashCode));
   GNUNET_assert (0 == gcry_sexp_new (&data, buff, bufSize, 0));
   GNUNET_free (buff);
-  GNUNET_assert (0 == gcry_pk_sign (&result, data, hostkey->sexp));
+  GNUNET_assert (0 == gcry_pk_sign (&result, data, key->sexp));
   gcry_sexp_release (data);
   GNUNET_assert (0 == key_from_sexp (&rval, result, "rsa", "s"));
   gcry_sexp_release (result);
diff --git a/src/util/getopt.c b/src/util/getopt.c
index e37390a3a..82d0baebd 100644
--- a/src/util/getopt.c
+++ b/src/util/getopt.c
@@ -987,7 +987,7 @@ GNgetopt_long (int argc,
 /**
  * Parse the command line.
  *
- * @param binaryOptions name of this binary / application
+ * @param binaryOptions Name of application with option summary
  * @param allOptions defined options and handlers
  * @param argc number of arguments
  * @param argv actual arguments
diff --git a/src/util/gnunet-service-resolver.c b/src/util/gnunet-service-resolver.c
index 304f11b7b..1dce5cedc 100644
--- a/src/util/gnunet-service-resolver.c
+++ b/src/util/gnunet-service-resolver.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file resolver/gnunet-service-resolver.c
+ * @file util/gnunet-service-resolver.c
  * @brief code to do DNS resolution
  * @author Christian Grothoff
  */
@@ -35,24 +35,55 @@
 #include "gnunet_time_lib.h"
 #include "resolver.h"
 
-
+/**
+ * A cached DNS lookup result.
+ */
 struct IPCache
 {
+  /**
+   * This is a linked list.
+   */
   struct IPCache *next;
+  
+  /**
+   * Hostname in human-readable form.
+   */
   char *addr;
+
+  /**
+   * Hostname in binary format.
+   */
   struct sockaddr *sa;
+  
+  /**
+   * Last time this entry was updated.
+   */
   struct GNUNET_TIME_Absolute last_refresh;
+
+  /**
+   * Last time this entry was requested.
+   */
   struct GNUNET_TIME_Absolute last_request;
-  unsigned int salen;
+
+  /**
+   * Number of bytes in sa.
+   */
+  socklen_t salen;
 };
 
 
+/**
+ * Start of the linked list of cached DNS lookup results.
+ */
 static struct IPCache *head;
 
 
-
-
 #if HAVE_GETNAMEINFO
+/**
+ * Resolve the given request using getnameinfo
+ *
+ * @param cache the request to resolve (and where to store the result)
+ */
 static void
 getnameinfo_resolve (struct IPCache *cache)
 {
@@ -69,6 +100,11 @@ getnameinfo_resolve (struct IPCache *cache)
 
 
 #if HAVE_GETHOSTBYADDR
+/**
+ * Resolve the given request using gethostbyaddr
+ *
+ * @param cache the request to resolve (and where to store the result)
+ */
 static void
 gethostbyaddr_resolve (struct IPCache *cache)
 {
@@ -92,7 +128,11 @@ gethostbyaddr_resolve (struct IPCache *cache)
 }
 #endif
 
-
+/**
+ * Resolve the given request using the available methods.
+ *
+ * @param cache the request to resolve (and where to store the result)
+ */
 static void
 cache_resolve (struct IPCache *cache)
 {
@@ -114,11 +154,13 @@ cache_resolve (struct IPCache *cache)
  * may not immediately result in the FQN (but instead in a
  * human-readable IP address).
  *
+ * @param client handle to the client making the request (for sending the reply)
  * @param sa should be of type "struct sockaddr*"
+ * @param salen number of bytes in sa
  */
 static void
 get_ip_as_string (struct GNUNET_SERVER_Client *client,
-                  const struct sockaddr *sav, socklen_t salen)
+                  const struct sockaddr *sa, socklen_t salen)
 {
   struct IPCache *cache;
   struct IPCache *prev;
@@ -134,7 +176,7 @@ get_ip_as_string (struct GNUNET_SERVER_Client *client,
   cache = head;
   prev = NULL;
   while ((cache != NULL) &&
-         ((cache->salen != salen) || (0 != memcmp (cache->sa, sav, salen))))
+         ((cache->salen != salen) || (0 != memcmp (cache->sa, sa, salen))))
     {
       if (GNUNET_TIME_absolute_get_duration (cache->last_request).value <
           60 * 60 * 1000)
@@ -178,7 +220,7 @@ get_ip_as_string (struct GNUNET_SERVER_Client *client,
       cache->next = head;
       cache->salen = salen;
       cache->sa = GNUNET_malloc (salen);
-      memcpy (cache->sa, sav, salen);
+      memcpy (cache->sa, sa, salen);
       cache->last_request = GNUNET_TIME_absolute_get ();
       cache->last_refresh = GNUNET_TIME_absolute_get ();
       cache->addr = NULL;
diff --git a/src/util/os_network.c b/src/util/os_network.c
index c78dc71c5..d18e5eb76 100644
--- a/src/util/os_network.c
+++ b/src/util/os_network.c
@@ -35,11 +35,11 @@
  * @brief Enumerate all network interfaces
  *
  * @param proc the callback function
- * @param cls closure for proc
+ * @param proc_cls closure for proc
  */
 void
 GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor proc,
-                                   void *cls)
+                                   void *proc_cls)
 {
 #ifdef MINGW
   PMIB_IFTABLE pTable;
@@ -148,7 +148,7 @@ GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor proc,
                 free (pszIfName);
 
               if (GNUNET_OK !=
-                  proc (cls,
+                  proc (proc_cls,
                         szEntry,
                         pAddrTable->table[dwIfIdx].dwIndex == dwExternalNIC,
                         NULL /* FIXME: pass actual IP address! */ ,
@@ -182,7 +182,7 @@ GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor proc,
                 alen = sizeof (struct sockaddr_in);
               else
                 alen = sizeof (struct sockaddr_in6);
-              if (GNUNET_OK != proc (cls,
+              if (GNUNET_OK != proc (proc_cls,
                                      ifa_ptr->ifa_name,
                                      0 == strcmp (ifa_ptr->ifa_name,
                                                   GNUNET_DEFAULT_INTERFACE),
@@ -255,7 +255,7 @@ GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor proc,
               a4.sin_family = AF_INET;
               a4.sin_addr = v4;
               if (GNUNET_OK !=
-                  proc (cls,
+                  proc (proc_cls,
                         ifc,
                         0 == strcmp (ifc, GNUNET_DEFAULT_INTERFACE),
                         (const struct sockaddr *) &a4, sizeof (a4)))
@@ -270,7 +270,7 @@ GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor proc,
               a6.sin6_addr = v6;
               fprintf (stderr, "procing %s\n", addrstr);
               if (GNUNET_OK !=
-                  proc (cls,
+                  proc (proc_cls,
                         ifc,
                         0 == strcmp (ifc, GNUNET_DEFAULT_INTERFACE),
                         (const struct sockaddr *) &a6, sizeof (a6)))
diff --git a/src/util/os_priority.c b/src/util/os_priority.c
index 46e2deb5c..6e18d9278 100644
--- a/src/util/os_priority.c
+++ b/src/util/os_priority.c
@@ -29,19 +29,23 @@
 #include "gnunet_os_lib.h"
 
 /**
- * Set our process priority
+ * Set process priority
+ *
+ * @param proc id of the process
+ * @param prio priority value
+ * @return GNUNET_OK on success, GNUNET_SYSERR on error
  */
 int
 GNUNET_OS_set_process_priority (pid_t proc,
-                                enum GNUNET_SCHEDULER_Priority eprio)
+                                enum GNUNET_SCHEDULER_Priority prio)
 {
   int prio = 0;
 
-  GNUNET_assert (eprio < GNUNET_SCHEDULER_PRIORITY_COUNT);
-  if (eprio == GNUNET_SCHEDULER_PRIORITY_KEEP)
+  GNUNET_assert (prio < GNUNET_SCHEDULER_PRIORITY_COUNT);
+  if (prio == GNUNET_SCHEDULER_PRIORITY_KEEP)
     return GNUNET_OK;
   /* convert to MINGW/Unix values */
-  switch (eprio)
+  switch (prio)
     {
     case GNUNET_SCHEDULER_PRIORITY_DEFAULT:
 #ifdef MINGW
diff --git a/src/util/pseudonym.c b/src/util/pseudonym.c
index 8687b5c4d..04a6a1f78 100644
--- a/src/util/pseudonym.c
+++ b/src/util/pseudonym.c
@@ -588,7 +588,7 @@ merge_meta_helper (void *cls,
 /**
  * Add a pseudonym to the set of known pseudonyms.
  * For all pseudonym advertisements that we discover
- * FSUI should automatically call this function.
+ * FS should automatically call this function.
  *
  * @param cfg overall configuration
  * @param id the pseudonym identifier
diff --git a/src/util/resolver.h b/src/util/resolver.h
index 31637f01d..5adf43633 100644
--- a/src/util/resolver.h
+++ b/src/util/resolver.h
@@ -20,7 +20,7 @@
 
 /**
  * @author Christian Grothoff
- * @file resolver/resolver.h
+ * @file util/resolver.h
  */
 #ifndef RESOLVER_H
 #define RESOLVER_H
diff --git a/src/util/resolver_api.c b/src/util/resolver_api.c
index cc81aa6b8..b2c8fda66 100644
--- a/src/util/resolver_api.c
+++ b/src/util/resolver_api.c
@@ -19,7 +19,7 @@
 */
 
 /**
- * @file resolver/resolver_api.c
+ * @file util/resolver_api.c
  * @brief resolver for writing a tool
  * @author Christian Grothoff
  */
diff --git a/src/util/strings.c b/src/util/strings.c
index 23e6cd85b..133fda857 100644
--- a/src/util/strings.c
+++ b/src/util/strings.c
@@ -353,37 +353,37 @@ GNUNET_STRINGS_filename_expand (const char *fil)
 /**
  * Give relative time in human-readable fancy format.
  *
- * @param del time in milli seconds
+ * @param delta time in milli seconds
  * @return time as human-readable string
  */
 char *
-GNUNET_STRINGS_relative_time_to_string (struct GNUNET_TIME_Relative del)
+GNUNET_STRINGS_relative_time_to_string (struct GNUNET_TIME_Relative delta)
 {
   const char *unit = _( /* time unit */ "ms");
   char *ret;
-  uint64_t delta = del.value;
+  uint64_t dval = delta.value;
 
-  if (delta > 5 * 1000)
+  if (dval > 5 * 1000)
     {
-      delta = delta / 1000;
+      dval = dval / 1000;
       unit = _( /* time unit */ "s");
-      if (delta > 5 * 60)
+      if (dval > 5 * 60)
         {
-          delta = delta / 60;
+          dval = dval / 60;
           unit = _( /* time unit */ "m");
-          if (delta > 5 * 60)
+          if (dval > 5 * 60)
             {
-              delta = delta / 60;
+              dval = dval / 60;
               unit = _( /* time unit */ "h");
-              if (delta > 5 * 24)
+              if (dval > 5 * 24)
                 {
-                  delta = delta / 24;
+                  dval = dval / 24;
                   unit = _( /* time unit */ " days");
                 }
             }
         }
     }
-  GNUNET_asprintf (&ret, "%llu%s", delta, unit);
+  GNUNET_asprintf (&ret, "%llu%s", dval, unit);
   return ret;
 }