[gnunet] 68/90: -DOC: Documentation cleanup pass through rest of UTIL libraries

[gnunet]

This is an automated email from the git hooks/post-receive script.

martin-schanzenbach pushed a commit to branch master
in repository gnunet.

commit 98594a4d88fe911b57505e94ab3a1a9a6219ea0e
Author: Willow Liquorice <willow@howhill.com>
AuthorDate: Wed Sep 7 22:26:23 2022 +0100

    -DOC: Documentation cleanup pass through rest of UTIL libraries
---
 src/include/gnunet_common.h         |  4 ++--
 src/include/gnunet_crypto_lib.h     | 12 ++++++------
 src/include/gnunet_disk_lib.h       |  2 +-
 src/include/gnunet_getopt_lib.h     |  1 -
 src/include/gnunet_mq_lib.h         | 18 +++++++++---------
 src/include/gnunet_strings_lib.h    |  4 ++--
 src/include/gnunet_time_lib.h       |  2 +-
 src/util/child_management.c         |  2 +-
 src/util/common_logging.c           | 38 +------------------------------------
 src/util/container_multihashmap32.c |  4 ++--
 src/util/crypto_rsa.c               |  2 +-
 src/util/gnunet-scrypt.c            |  1 -
 src/util/gnunet-service-resolver.c  |  6 +++---
 src/util/socks.c                    |  2 +-
 14 files changed, 30 insertions(+), 68 deletions(-)

diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h
index 5035d6baa..8c58fd6e3 100644
--- a/src/include/gnunet_common.h
+++ b/src/include/gnunet_common.h
@@ -1510,7 +1510,7 @@ GNUNET_is_zero_ (const void *a,
  *        will be updated to reflect the new address. The TYPE of
  *        arr is important since size is the number of elements and
  *        not the size in bytes
- * @param len the number of elements in the existing vector (number
+ * @param len2 the number of elements in the existing vector (number
  *        of elements to copy over), will be updated with the new
  *        array size
 
@@ -1743,7 +1743,7 @@ GNUNET_copy_message (const struct GNUNET_MessageHeader 
*msg);
  * Set the async scope for the current thread.
  *
  * @param aid the async scope identifier
- * @param old_scope[out] location to save the old scope
+ * @param[out] old_scope location to save the old scope
  */
 void
 GNUNET_async_scope_enter (const struct GNUNET_AsyncScopeId *aid,
diff --git a/src/include/gnunet_crypto_lib.h b/src/include/gnunet_crypto_lib.h
index cb0b0d9a3..36e6743b3 100644
--- a/src/include/gnunet_crypto_lib.h
+++ b/src/include/gnunet_crypto_lib.h
@@ -1431,7 +1431,7 @@ enum GNUNET_GenericReturnValue
 GNUNET_CRYPTO_eddsa_private_key_from_string (
   const char *enc,
   size_t enclen,
-  struct GNUNET_CRYPTO_EddsaPrivateKey *pub);
+  struct GNUNET_CRYPTO_EddsaPrivateKey *priv);
 
 
 /**
@@ -1683,7 +1683,7 @@ GNUNET_CRYPTO_ecc_dlog_prepare (unsigned int max,
  * Calculate ECC discrete logarithm for small factors.
  * Opposite of #GNUNET_CRYPTO_ecc_dexp().
  *
- * @param dlc precalculated values, determine range of factors
+ * @param edc precalculated values, determine range of factors
  * @param input point on the curve to factor
  * @return INT_MAX if dlog failed, otherwise the factor
  */
@@ -1954,7 +1954,7 @@ GNUNET_CRYPTO_ecdsa_sign_ (
  *
  * @param priv
  * @param data
- * @param len
+ * @param size
  * @param sig
  * @return enum GNUNET_GenericReturnValue
  */
@@ -2239,7 +2239,7 @@ GNUNET_CRYPTO_ecdsa_public_key_derive (
  * @param label label to use for key deriviation
  * @param context additional context to use for HKDF of 'h';
  *        typically the name of the subsystem/application
- * @param purp the signature purpose
+ * @param purpose the signature purpose
  * @param sig the resulting signature
  * @return GNUNET_OK on success
  */
@@ -2304,7 +2304,7 @@ GNUNET_CRYPTO_eddsa_public_key_derive (
  * @param label label to use for key deriviation
  * @param context additional context to use for HKDF of 'h';
  *        typically the name of the subsystem/application
- * @param purp the signature purpose
+ * @param purpose the signature purpose
  * @param sig the resulting signature
  * @return GNUNET_OK on success
  */
@@ -2690,7 +2690,7 @@ GNUNET_CRYPTO_rsa_public_key_cmp (const struct 
GNUNET_CRYPTO_RsaPublicKey *p1,
  * Blinds the given message with the given blinding key
  *
  * @param hash hash of the message to sign
- * @param bkey the blinding key
+ * @param bks the blinding key
  * @param pkey the public key of the signer
  * @param[out] buf set to a buffer with the blinded message to be signed
  * @param[out] buf_size number of bytes stored in @a buf
diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h
index 71c1f88a5..c76cdc231 100644
--- a/src/include/gnunet_disk_lib.h
+++ b/src/include/gnunet_disk_lib.h
@@ -674,7 +674,7 @@ GNUNET_DISK_directory_scan (const char *dir_name,
  * Currently, the glob_pattern only supports asterisks in the last
  * path component.
  *
- * @param glob_patterb the glob pattern to search for
+ * @param glob_pattern the glob pattern to search for
  * @param callback the method to call for each file
  * @param callback_cls closure for @a callback
  * @return the number of files found, -1 on error
diff --git a/src/include/gnunet_getopt_lib.h b/src/include/gnunet_getopt_lib.h
index c7c1d57a3..87ad591b7 100644
--- a/src/include/gnunet_getopt_lib.h
+++ b/src/include/gnunet_getopt_lib.h
@@ -404,7 +404,6 @@ GNUNET_GETOPT_option_timestamp (char shortName,
  *
  * @param shortName short name of the option
  * @param name long name of the option
- * @param argumentHelp help text for the option argument
  * @param description long help text for the option
  * @param[out] val set to 1 if the option is present
  */
diff --git a/src/include/gnunet_mq_lib.h b/src/include/gnunet_mq_lib.h
index a6bd58558..a06fb4eb7 100644
--- a/src/include/gnunet_mq_lib.h
+++ b/src/include/gnunet_mq_lib.h
@@ -390,9 +390,9 @@ typedef void
  * FIFO of envelopes independent of MQ itself and wants to
  * re-use the pointers internal to @a env.  Use with caution.
  *
- * @param[in|out] env_head of envelope DLL
- * @param[in|out] env_tail tail of envelope DLL
- * @param[in|out] env element to insert at the tail
+ * @param[in,out] env_head of envelope DLL
+ * @param[in,out] env_tail tail of envelope DLL
+ * @param[in,out] env element to insert at the tail
  */
 void
 GNUNET_MQ_dll_insert_head (struct GNUNET_MQ_Envelope **env_head,
@@ -408,9 +408,9 @@ GNUNET_MQ_dll_insert_head (struct GNUNET_MQ_Envelope 
**env_head,
  * FIFO of envelopes independent of MQ itself and wants to
  * re-use the pointers internal to @a env.  Use with caution.
  *
- * @param[in|out] env_head of envelope DLL
- * @param[in|out] env_tail tail of envelope DLL
- * @param[in|out] env element to insert at the tail
+ * @param[in,out] env_head of envelope DLL
+ * @param[in,out] env_tail tail of envelope DLL
+ * @param[in,out] env element to insert at the tail
  */
 void
 GNUNET_MQ_dll_insert_tail (struct GNUNET_MQ_Envelope **env_head,
@@ -426,9 +426,9 @@ GNUNET_MQ_dll_insert_tail (struct GNUNET_MQ_Envelope 
**env_head,
  * FIFO of envelopes independent of MQ itself and wants to
  * re-use the pointers internal to @a env.  Use with caution.
  *
- * @param[in|out] env_head of envelope DLL
- * @param[in|out] env_tail tail of envelope DLL
- * @param[in|out] env element to remove from the DLL
+ * @param[in,out] env_head of envelope DLL
+ * @param[in,out] env_tail tail of envelope DLL
+ * @param[in,out] env element to remove from the DLL
  */
 void
 GNUNET_MQ_dll_remove (struct GNUNET_MQ_Envelope **env_head,
diff --git a/src/include/gnunet_strings_lib.h b/src/include/gnunet_strings_lib.h
index e96888db5..7e06768b8 100644
--- a/src/include/gnunet_strings_lib.h
+++ b/src/include/gnunet_strings_lib.h
@@ -403,7 +403,7 @@ GNUNET_STRINGS_base64_encode (const void *in,
  *
  * @param data the data to decode
  * @param len the length of the input
- * @param output where to write the output (*output should be NULL,
+ * @param out where to write the output (*out should be NULL,
  *   is allocated)
  * @return the size of the output
  */
@@ -448,7 +448,7 @@ GNUNET_STRINGS_base64_decode (const char *data,
  *
  * @param data the data to decode
  * @param len the length of the input
- * @param output where to write the output (*output should be NULL,
+ * @param out where to write the output (*out should be NULL,
  *   is allocated)
  * @return the size of the output
  */
diff --git a/src/include/gnunet_time_lib.h b/src/include/gnunet_time_lib.h
index d753d62f7..e66ce6ea9 100644
--- a/src/include/gnunet_time_lib.h
+++ b/src/include/gnunet_time_lib.h
@@ -242,7 +242,7 @@ GNUNET_TIME_timestamp2s (struct GNUNET_TIME_Timestamp ts);
  * Note that the returned value will be overwritten if this function
  * is called again.
  *
- * @param t the absolute time to convert
+ * @param ts the absolute time to convert
  * @return timestamp in human-readable form in local time
  */
 const char *
diff --git a/src/util/child_management.c b/src/util/child_management.c
index 832e05ece..8c413a8b5 100644
--- a/src/util/child_management.c
+++ b/src/util/child_management.c
@@ -197,7 +197,7 @@ child_management_done (void)
  * Adding a child process to be monitored by the child management.
  *
  * @param proc The child process to be monitored.
- * @param cp The callback to be called, when the child process completed.
+ * @param cb The callback to be called, when the child process completed.
  * @param cb_cls The closure for the callback.
  * @return An handle for the the child being monitored.
  */
diff --git a/src/util/common_logging.c b/src/util/common_logging.c
index 27d9ca3ce..9fa848224 100644
--- a/src/util/common_logging.c
+++ b/src/util/common_logging.c
@@ -1154,15 +1154,6 @@ GNUNET_h2s2 (const struct GNUNET_HashCode *hc)
 }
 
 
-/**
- * @ingroup logging
- * Convert a public key value to a string (for printing debug messages).
- * This is one of the very few calls in the entire API that is
- * NOT reentrant!
- *
- * @param hc the hash code
- * @return string
- */
 const char *
 GNUNET_p2s (const struct GNUNET_CRYPTO_EddsaPublicKey *p)
 {
@@ -1176,15 +1167,6 @@ GNUNET_p2s (const struct GNUNET_CRYPTO_EddsaPublicKey *p)
 }
 
 
-/**
- * @ingroup logging
- * Convert a public key value to a string (for printing debug messages).
- * This is one of the very few calls in the entire API that is
- * NOT reentrant!
- *
- * @param hc the hash code
- * @return string
- */
 const char *
 GNUNET_p2s2 (const struct GNUNET_CRYPTO_EddsaPublicKey *p)
 {
@@ -1198,15 +1180,6 @@ GNUNET_p2s2 (const struct GNUNET_CRYPTO_EddsaPublicKey 
*p)
 }
 
 
-/**
- * @ingroup logging
- * Convert a public key value to a string (for printing debug messages).
- * This is one of the very few calls in the entire API that is
- * NOT reentrant!
- *
- * @param hc the hash code
- * @return string
- */
 const char *
 GNUNET_e2s (const struct GNUNET_CRYPTO_EcdhePublicKey *p)
 {
@@ -1220,15 +1193,6 @@ GNUNET_e2s (const struct GNUNET_CRYPTO_EcdhePublicKey *p)
 }
 
 
-/**
- * @ingroup logging
- * Convert a public key value to a string (for printing debug messages).
- * This is one of the very few calls in the entire API that is
- * NOT reentrant!
- *
- * @param hc the hash code
- * @return string
- */
 const char *
 GNUNET_e2s2 (const struct GNUNET_CRYPTO_EcdhePublicKey *p)
 {
@@ -1476,7 +1440,7 @@ GNUNET_log_config_invalid (enum GNUNET_ErrorType kind,
  * Set the async scope for the current thread.
  *
  * @param aid the async scope identifier
- * @param old_scope[out] location to save the old scope
+ * @param[out] old_scope location to save the old scope
  */
 void
 GNUNET_async_scope_enter (const struct GNUNET_AsyncScopeId *aid,
diff --git a/src/util/container_multihashmap32.c 
b/src/util/container_multihashmap32.c
index ccedd1bbb..2416c40f2 100644
--- a/src/util/container_multihashmap32.c
+++ b/src/util/container_multihashmap32.c
@@ -259,11 +259,11 @@ GNUNET_CONTAINER_multihashmap32_iterate (
 
 
 /**
- * We are about to free() the @a bme, make sure it is not in
+ * We are about to free() the @a me, make sure it is not in
  * the list of next values for any iterator in the @a map's next_cache.
  *
  * @param map the map to check
- * @param bme the entry that is about to be free'd
+ * @param me the entry that is about to be free'd
  */
 static void
 update_next_cache (struct GNUNET_CONTAINER_MultiHashMap32 *map,
diff --git a/src/util/crypto_rsa.c b/src/util/crypto_rsa.c
index 4b8e5a5ce..325a1fe86 100644
--- a/src/util/crypto_rsa.c
+++ b/src/util/crypto_rsa.c
@@ -709,7 +709,7 @@ rsa_blinding_key_free (struct RsaBlindingKey *bkey)
  * Print an MPI to a newly created buffer
  *
  * @param v MPI to print.
- * @param[out] newly allocated buffer containing the result
+ * @param[out] buffer newly allocated buffer containing the result
  * @return number of bytes stored in @a buffer
  */
 static size_t
diff --git a/src/util/gnunet-scrypt.c b/src/util/gnunet-scrypt.c
index ad46e3f39..3c219ef4f 100644
--- a/src/util/gnunet-scrypt.c
+++ b/src/util/gnunet-scrypt.c
@@ -81,7 +81,6 @@ shutdown_task (void *cls)
  * Find our proof of work.
  *
  * @param cls closure (unused)
- * @param tc task context
  */
 static void
 find_proof (void *cls)
diff --git a/src/util/gnunet-service-resolver.c 
b/src/util/gnunet-service-resolver.c
index 8a89fbb37..bb70ac3bd 100644
--- a/src/util/gnunet-service-resolver.c
+++ b/src/util/gnunet-service-resolver.c
@@ -313,7 +313,7 @@ extract_search_domain (const char *line, size_t line_len)
 /**
  * Reads the list of nameservers from /etc/resolve.conf
  *
- * @param server_addrs[out] a list of null-terminated server address strings
+ * @param[out] server_addrs a list of null-terminated server address strings
  * @return the number of server addresses in @a server_addrs, -1 on error
  */
 static int
@@ -670,8 +670,8 @@ try_cache (const char *hostname,
  * @param hostname DNS name to query
  * @param type requested DNS record type
  * @param dns_id what should be the DNS request ID
- * @param packet_buf[out] where to write the request packet
- * @param packet_size[out] set to size of @a packet_buf on success
+ * @param[out] packet_buf where to write the request packet
+ * @param[out] packet_size set to size of @a packet_buf on success
  * @return #GNUNET_OK on success
  */
 static int
diff --git a/src/util/socks.c b/src/util/socks.c
index 5c9f8a5f8..a1990ec8b 100644
--- a/src/util/socks.c
+++ b/src/util/socks.c
@@ -516,7 +516,7 @@ GNUNET_SOCKS_init_handshake_noauth ()
  * and port.
  *
  * @param ih SOCKS5 handshake
- * @param hostname
+ * @param host
  * @param port
  */
 void

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.