better comments

14 files changed, 60 insertions, 53 deletions

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