From 1d0bbddfefaefb6e3f5cd240e56462a6bef2fa09 Mon Sep 17 00:00:00 2001
From: Willow Liquorice <willow@howhill.com>
Date: Wed, 7 Sep 2022 20:41:38 +0100
Subject: -DOC: Documentation cleanup pass through TRANSPORT ('missing
 argument' warnings)

---
 .../gnunet_transport_communication_service.h       |  2 +-
 src/transport/gnunet-communicator-tcp.c            | 16 ++++++++--------
 src/transport/gnunet-communicator-udp.c            | 12 ++++++------
 src/transport/gnunet-service-tng.c                 | 22 +++++++++++-----------
 src/transport/gnunet-service-transport.c           |  2 +-
 .../gnunet-service-transport_manipulation.c        |  4 ++--
 src/transport/gnunet-service-transport_plugins.c   |  1 -
 src/transport/plugin_transport_http_server.c       |  2 +-
 src/transport/plugin_transport_tcp.c               |  2 +-
 src/transport/plugin_transport_udp.c               |  2 +-
 src/transport/transport-testing-cmds.h             | 10 +++++-----
 src/transport/transport-testing-communicator.c     | 15 +++------------
 src/transport/transport_api2_communication.c       |  9 ---------
 src/transport/transport_api_address_to_string.c    |  4 ++--
 .../transport_api_cmd_backchannel_check.c          | 12 ------------
 src/transport/transport_api_cmd_connecting_peers.c | 11 -----------
 src/transport/transport_api_core.c                 |  2 +-
 17 files changed, 43 insertions(+), 85 deletions(-)

(limited to 'src')

diff --git a/src/include/gnunet_transport_communication_service.h b/src/include/gnunet_transport_communication_service.h
index 7bab86e1a..6c99de78e 100644
--- a/src/include/gnunet_transport_communication_service.h
+++ b/src/include/gnunet_transport_communication_service.h
@@ -284,7 +284,7 @@ GNUNET_TRANSPORT_communicator_mq_add (
  * Notify transport service that an MQ was updated
  *
  * @param ch connection to transport service
- * @param qh the queue to update
+ * @param u_qh the queue to update
  * @param q_len number of messages that can be send through this queue
  * @param priority queue priority. Queues with highest priority should be
  *                 used
diff --git a/src/transport/gnunet-communicator-tcp.c b/src/transport/gnunet-communicator-tcp.c
index 6d7a151ec..9612c8848 100644
--- a/src/transport/gnunet-communicator-tcp.c
+++ b/src/transport/gnunet-communicator-tcp.c
@@ -981,7 +981,7 @@ queue_destroy (struct Queue *queue)
  * @param[in,out] hmac_secret secret for HMAC calculation
  * @param buf buffer to MAC
  * @param buf_size number of bytes in @a buf
- * @param smac[out] where to write the HMAC
+ * @param[out] smac where to write the HMAC
  */
 static void
 calculate_hmac (struct GNUNET_HashCode *hmac_secret,
@@ -1155,8 +1155,8 @@ pass_plaintext_to_core (struct Queue *queue,
  *
  * @param dh shared secret
  * @param pid decrypting peer's identity
- * @param cipher[out] cipher to initialize
- * @param hmac_key[out] HMAC key to initialize
+ * @param[out] cipher cipher to initialize
+ * @param[out] hmac_key HMAC key to initialize
  */
 static void
 setup_cipher (const struct GNUNET_HashCode *dh,
@@ -1287,7 +1287,7 @@ rekey_monotime_cb (void *cls,
  * Setup cipher of @a queue for decryption.
  *
  * @param ephemeral ephemeral key we received from the other peer
- * @param queue[in,out] queue to initialize decryption cipher for
+ * @param[in,out] queue queue to initialize decryption cipher for
  */
 static void
 setup_in_cipher (const struct GNUNET_CRYPTO_EcdhePublicKey *ephemeral,
@@ -1448,8 +1448,8 @@ handshake_ack_monotime_cb (void *cls,
  * @param queue The queue context.
  */
 static void
-send_challenge (struct GNUNET_CRYPTO_ChallengeNonceP challenge, struct
-                Queue *queue)
+send_challenge (struct GNUNET_CRYPTO_ChallengeNonceP challenge, 
+		struct Queue *queue)
 {
   struct TCPConfirmationAck tca;
   struct TcpHandshakeAckSignature thas;
@@ -2608,7 +2608,7 @@ handshake_monotime_cb (void *cls,
  * Note that #setup_in_cipher() must have already been called.
  *
  * @param queue queue to decrypt initial bytes from other peer for
- * @param tc[out] where to store the result
+ * @param[out] tc where to store the result
  * @param ibuf incoming data, of size
  *        `INITIAL_KX_SIZE`
  * @return #GNUNET_OK if the signature was OK, #GNUNET_SYSERR if not
@@ -3174,7 +3174,7 @@ enc_notify_cb (void *cls,
  * a function to call whenever our set of 'valid' addresses changes.
  *
  * @param cls closure
- * @param app_ctx[in,out] location where the app can store stuff
+ * @param[in,out] app_ctx location where the app can store stuff
  *                  on add and retrieve it on remove
  * @param add_remove #GNUNET_YES to add a new public IP address,
  *                   #GNUNET_NO to remove a previous (now invalid) one
diff --git a/src/transport/gnunet-communicator-udp.c b/src/transport/gnunet-communicator-udp.c
index 70848ff79..0f9a95619 100644
--- a/src/transport/gnunet-communicator-udp.c
+++ b/src/transport/gnunet-communicator-udp.c
@@ -998,7 +998,7 @@ kce_destroy (struct KeyCacheEntry *kce)
  *
  * @param msec master secret for HMAC calculation
  * @param serial number for the @a smac calculation
- * @param kid[out] where to write the key ID
+ * @param[out] kid where to write the key ID
  */
 static void
 get_kid (const struct GNUNET_HashCode *msec,
@@ -1130,8 +1130,8 @@ sender_destroy (struct SenderAddress *sender)
  *
  * @param msec master secret for calculation
  * @param serial number for the @a smac calculation
- * @param key[out] where to write the decryption key
- * @param iv[out] where to write the IV
+ * @param[out] key where to write the decryption key
+ * @param[out] iv where to write the IV
  */
 static void
 get_iv_key (const struct GNUNET_HashCode *msec,
@@ -1237,7 +1237,7 @@ check_timeouts (void *cls)
 /**
  * Calculate cmac from master in @a ss.
  *
- * @param ss[in,out] data structure to complete
+ * @param[in,out] ss data structure to complete
  */
 static void
 calculate_cmac (struct SharedSecret *ss)
@@ -1397,7 +1397,7 @@ setup_shared_secret_dec (const struct GNUNET_CRYPTO_EcdhePublicKey *ephemeral)
  * Setup shared secret for encryption.
  *
  * @param ephemeral ephemeral key we are sending to the other peer
- * @param receiver[in,out] queue to initialize encryption key for
+ * @param[in,out] receiver queue to initialize encryption key for
  * @return new shared secret
  */
 static struct SharedSecret *
@@ -2198,7 +2198,7 @@ setup_sender (const struct GNUNET_PeerIdentity *target,
 /**
  * Check signature from @a uc against @a ephemeral.
  *
- * @param ephermal key that is signed
+ * @param ephemeral key that is signed
  * @param uc signature of claimant
  * @return #GNUNET_OK if signature is valid
  */
diff --git a/src/transport/gnunet-service-tng.c b/src/transport/gnunet-service-tng.c
index 9b2b920d1..333211ce1 100644
--- a/src/transport/gnunet-service-tng.c
+++ b/src/transport/gnunet-service-tng.c
@@ -4081,7 +4081,7 @@ client_send_response (struct PendingMessage *pm)
  *
  * @param dv data structure to pick paths from
  * @param options constraints to satisfy
- * @param hops_array[out] set to the result
+ * @param[out] hops_array set to the result
  * @param hops_array_length length of the @a hops_array
  * @return number of entries set in @a hops_array
  */
@@ -4329,7 +4329,7 @@ check_communicator_backchannel (
  * Ensure ephemeral keys in our @a dv are current. If no current one exists,
  * set it up.
  *
- * @param dv[in,out] virtual link to update ephemeral for
+ * @param[in,out] dv virtual link to update ephemeral for
  */
 static void
 update_ephemeral (struct DistanceVector *dv)
@@ -4562,7 +4562,7 @@ struct DVKeyState
  *
  * @param km raw master secret
  * @param iv initialization vector
- * @param key[out] symmetric cipher and HMAC state to generate
+ * @param[out] key symmetric cipher and HMAC state to generate
  */
 static void
 dv_setup_key_state_from_km (const struct GNUNET_HashCode *km,
@@ -4604,7 +4604,7 @@ dv_setup_key_state_from_km (const struct GNUNET_HashCode *km,
  * @param priv_ephemeral ephemeral private key to use
  * @param target the target peer to encrypt to
  * @param iv unique IV to use
- * @param key[out] set to the key material
+ * @param[out] key set to the key material
  */
 static void
 dh_key_derive_eph_pid (
@@ -4629,7 +4629,7 @@ dh_key_derive_eph_pid (
  * @param priv_ephemeral ephemeral private key to use
  * @param target the target peer to encrypt to
  * @param iv unique IV to use
- * @param key[out] set to the key material
+ * @param[out] key set to the key material
  */
 static void
 dh_key_derive_eph_pub (const struct GNUNET_CRYPTO_EcdhePublicKey *pub_ephemeral,
@@ -4650,7 +4650,7 @@ dh_key_derive_eph_pub (const struct GNUNET_CRYPTO_EcdhePublicKey *pub_ephemeral,
  * material from @a key.
  *
  * @param key key material (from DH)
- * @param hmac[out] set to the HMAC
+ * @param[out] hmac set to the HMAC
  * @param data data to perform HMAC calculation over
  * @param data_size number of bytes in @a data
  */
@@ -4740,7 +4740,7 @@ typedef void (*DVMessageHandler) (void *cls,
  * @param use function to call with the encapsulated message
  * @param use_cls closure for @a use
  * @param options whether path must be confirmed or not, to be passed to @a use
- * @param shall this TransportDVBoxMessage be forwarded without flow control.
+ * @param without_fc shall this TransportDVBoxMessage be forwarded without flow control.
  * @return expected RTT for transmission, #GNUNET_TIME_UNIT_FOREVER_REL if sending failed
  */
 static struct GNUNET_TIME_Relative
@@ -6147,7 +6147,7 @@ handle_reliability_box (void *cls,
  * so, purge ancient statistics (more than GOODPUT_AGING_SLOTS before
  * the current age)
  *
- * @param pd[in,out] data to update
+ * @param[in,out] pd data to update
  * @param age current age
  */
 static void
@@ -6173,7 +6173,7 @@ update_pd_age (struct PerformanceData *pd, unsigned int age)
  * Update @a pd based on the latest @a rtt and the number of bytes
  * that were confirmed to be successfully transmitted.
  *
- * @param pd[in,out] data to update
+ * @param[in,out] pd data to update
  * @param rtt latest round-trip time
  * @param bytes_transmitted_ok number of bytes receiver confirmed as received
  */
@@ -8086,7 +8086,7 @@ handle_dv_box (void *cls, const struct TransportDVBoxMessage *dvb)
  * Client notified us about transmission from a peer.  Process the request.
  *
  * @param cls a `struct TransportClient` which sent us the message
- * @param obm the send message that was sent
+ * @param im the send message that was sent
  * @return #GNUNET_YES if message is well-formed
  */
 static int
@@ -9302,7 +9302,7 @@ struct PendingMessageScoreContext
  * Select the best pending message from @a vl for transmission
  * via @a queue.
  *
- * @param sc[in,out] best message so far (NULL for none), plus scoring data
+ * @param[in,out] sc best message so far (NULL for none), plus scoring data
  * @param queue the queue that will be used for transmission
  * @param vl the virtual link providing the messages
  * @param dvh path we are currently considering, or NULL for none
diff --git a/src/transport/gnunet-service-transport.c b/src/transport/gnunet-service-transport.c
index 463bcc628..93790e293 100644
--- a/src/transport/gnunet-service-transport.c
+++ b/src/transport/gnunet-service-transport.c
@@ -2120,7 +2120,7 @@ free_blacklist_entry (void *cls,
  * Set traffic metric to manipulate
  *
  * @param cls closure
- * @param message containing information
+ * @param tm message containing information
  */
 static void
 handle_client_set_metric (void *cls, const struct TrafficMetricMessage *tm)
diff --git a/src/transport/gnunet-service-transport_manipulation.c b/src/transport/gnunet-service-transport_manipulation.c
index 04d1774c0..9f39b2dca 100644
--- a/src/transport/gnunet-service-transport_manipulation.c
+++ b/src/transport/gnunet-service-transport_manipulation.c
@@ -168,7 +168,7 @@ static struct GNUNET_SCHEDULER_Task *generic_send_delay_task;
 /**
  * Set traffic metric to manipulate
  *
- * @param message containing information
+ * @param tm message containing information
  */
 void
 GST_manipulation_set_metric (const struct TrafficMetricMessage *tm)
@@ -349,7 +349,7 @@ GST_manipulation_send (const struct GNUNET_PeerIdentity *target,
  *
  * @param address binary address
  * @param session the session
- * @param prop[IN|OUT] metrics to modify
+ * @param[in,out] prop metrics to modify
  */
 void
 GST_manipulation_manipulate_metrics (const struct GNUNET_HELLO_Address *address,
diff --git a/src/transport/gnunet-service-transport_plugins.c b/src/transport/gnunet-service-transport_plugins.c
index 1a22335f4..218ef80ab 100644
--- a/src/transport/gnunet-service-transport_plugins.c
+++ b/src/transport/gnunet-service-transport_plugins.c
@@ -83,7 +83,6 @@ static struct TransportPlugin *plugins_tail;
  *
  * @param cls closure
  * @param address address to update metrics for
- * @param session the session
  * @param distance new distance
  */
 static void
diff --git a/src/transport/plugin_transport_http_server.c b/src/transport/plugin_transport_http_server.c
index 78b030e9a..3ad2356b0 100644
--- a/src/transport/plugin_transport_http_server.c
+++ b/src/transport/plugin_transport_http_server.c
@@ -2563,7 +2563,7 @@ server_remove_address (void *cls,
  * Our external IP address/port mapping has changed.
  *
  * @param cls closure, the 'struct LocalAddrList'
- * @param app_ctx[in,out] location where the app can store stuff
+ * @param[in,out] app_ctx location where the app can store stuff
  *                  on add and retrieve it on remove
  * @param add_remove #GNUNET_YES to mean the new public IP address, #GNUNET_NO to mean
  *     the previous (now invalid) one
diff --git a/src/transport/plugin_transport_tcp.c b/src/transport/plugin_transport_tcp.c
index ac4cc672f..ceae64709 100644
--- a/src/transport/plugin_transport_tcp.c
+++ b/src/transport/plugin_transport_tcp.c
@@ -1418,7 +1418,7 @@ notify_session_monitor (struct Plugin *plugin,
  * Our external IP address/port mapping has changed.
  *
  * @param cls closure, the `struct Plugin`
- * @param app_ctx[in,out] location where the app can store stuff
+ * @param[in,out] app_ctx location where the app can store stuff
  *                  on add and retrieve it on remove
  * @param add_remove #GNUNET_YES to mean the new public IP address, #GNUNET_NO to mean
  *     the previous (now invalid) one
diff --git a/src/transport/plugin_transport_udp.c b/src/transport/plugin_transport_udp.c
index 2db31caa3..0d3ca449d 100644
--- a/src/transport/plugin_transport_udp.c
+++ b/src/transport/plugin_transport_udp.c
@@ -1254,7 +1254,7 @@ udp_plugin_check_address (void *cls, const void *addr, size_t addrlen)
  * Our external IP address/port mapping has changed.
  *
  * @param cls closure, the `struct Plugin`
- * @param app_ctx[in,out] location where the app can store stuff
+ * @param[in,out] app_ctx location where the app can store stuff
  *                  on add and retrieve it on remove
  * @param add_remove #GNUNET_YES to mean the new public IP address,
  *                   #GNUNET_NO to mean the previous (now invalid) one
diff --git a/src/transport/transport-testing-cmds.h b/src/transport/transport-testing-cmds.h
index 5a3fb22d6..c577feb34 100644
--- a/src/transport/transport-testing-cmds.h
+++ b/src/transport/transport-testing-cmds.h
@@ -227,9 +227,9 @@ GNUNET_TRANSPORT_cmd_stop_peer (const char *label,
  *
  * @param label name for command
  * @param start_peer_label Label of the cmd to start a peer.
- * @param create_peer_label Label of the cmd which started the test system.
+ * @param create_label Label of the cmd which started the test system.
  * @param num Number globally identifying the node.
- * @param The topology for the test setup.
+ * @param topology The topology for the test setup.
  * @param additional_connects Number of additional connects this cmd will wait for not triggered by this cmd.
  * @return command.
  */
@@ -248,9 +248,9 @@ GNUNET_TRANSPORT_cmd_connect_peers (
  *
  * @param label name for command.
  * @param start_peer_label Label of the cmd to start a peer.
- * @param create_peer_label Label of the cmd which started the test system.
+ * @param create_label Label of the cmd which started the test system.
  * @param num Number globally identifying the node.
- * @param The topology for the test setup.
+ * @param topology The topology for the test setup.
  * @return command.
  */
 struct GNUNET_TESTING_Command
@@ -271,7 +271,7 @@ GNUNET_TRANSPORT_cmd_send_simple (const char *label,
  * @param num Number globally identifying the node.
  * @param node_n The number of the node in a network namespace.
  * @param namespace_n The number of the network namespace.
- * @param The topology for the test setup.
+ * @param topology The topology for the test setup.
  * @return command.
  */
 struct GNUNET_TESTING_Command
diff --git a/src/transport/transport-testing-communicator.c b/src/transport/transport-testing-communicator.c
index ce4af01f2..1bf88bb3d 100644
--- a/src/transport/transport-testing-communicator.c
+++ b/src/transport/transport-testing-communicator.c
@@ -232,7 +232,7 @@ check_communicator_backchannel (void *cls,
  * Pass the message to the client.
  *
  * @param cls Closure - communicator handle
- * @param msg Message
+ * @param bc_msg Message
  */
 static void
 handle_communicator_backchannel (void *cls,
@@ -283,7 +283,7 @@ handle_communicator_backchannel (void *cls,
  * Address of our peer added.  Test message is well-formed.
  *
  * @param cls the client
- * @param aam the send message that was sent
+ * @param msg the send message that was sent
  * @return #GNUNET_OK if message is well-formed
  */
 static int
@@ -365,7 +365,7 @@ check_incoming_msg (void *cls,
  * Pass the message to the client.
  *
  * @param cls Closure - communicator handle
- * @param msg Message
+ * @param inc_msg Message
  */
 static void
 handle_incoming_msg (void *cls,
@@ -1146,15 +1146,6 @@ GNUNET_TRANSPORT_TESTING_transport_communicator_open_queue (
 }
 
 
-/**
- * @brief Instruct communicator to send data
- *
- * @param tc_queue The queue to use for sending
- * @param cont function to call when done sending
- * @param cont_cls closure for @a cont
- * @param payload Data to send
- * @param payload_size Size of the @a payload
- */
 void
 GNUNET_TRANSPORT_TESTING_transport_communicator_send
   (struct GNUNET_TRANSPORT_TESTING_TransportCommunicatorHandle *tc_h,
diff --git a/src/transport/transport_api2_communication.c b/src/transport/transport_api2_communication.c
index aaab5df1c..3bfa53ad9 100644
--- a/src/transport/transport_api2_communication.c
+++ b/src/transport/transport_api2_communication.c
@@ -953,15 +953,6 @@ GNUNET_TRANSPORT_communicator_mq_add (
 }
 
 
-/**
- * Notify transport service that an MQ was updated
- *
- * @param ch connection to transport service
- * @param qh the queue to update
- * @param q_len number of messages that can be send through this queue
- * @param priority queue priority. Queues with highest priority should be
- *                 used
- */
 void
 GNUNET_TRANSPORT_communicator_mq_update (
   struct GNUNET_TRANSPORT_CommunicatorHandle *ch,
diff --git a/src/transport/transport_api_address_to_string.c b/src/transport/transport_api_address_to_string.c
index c7de39ea8..5b234f802 100644
--- a/src/transport/transport_api_address_to_string.c
+++ b/src/transport/transport_api_address_to_string.c
@@ -56,7 +56,7 @@ struct GNUNET_TRANSPORT_AddressToStringContext
  * Function called with responses from the service.
  *
  * @param cls our `struct GNUNET_TRANSPORT_AddressToStringContext *`
- * @param msg message with the human-readable address
+ * @param atsm message with the human-readable address
  * @return #GNUNET_OK if message is well-formed
  */
 static int
@@ -97,7 +97,7 @@ check_reply (void *cls,
  * Function called with responses from the service.
  *
  * @param cls our `struct GNUNET_TRANSPORT_AddressToStringContext *`
- * @param msg message with the human-readable address
+ * @param atsm message with the human-readable address
  */
 static void
 handle_reply (void *cls,
diff --git a/src/transport/transport_api_cmd_backchannel_check.c b/src/transport/transport_api_cmd_backchannel_check.c
index 4ffd96210..47a3190a3 100644
--- a/src/transport/transport_api_cmd_backchannel_check.c
+++ b/src/transport/transport_api_cmd_backchannel_check.c
@@ -557,18 +557,6 @@ backchannel_check_cleanup (void *cls)
 }
 
 
-/**
- * Create command.
- *
- * @param label name for command.
- * @param start_peer_label Label of the cmd to start a peer.
- * @param create_label Label of the cmd to create the testing system.
- * @param num Number globally identifying the node.
- * @param node_n The number of the node in a network namespace.
- * @param namespace_n The number of the network namespace.
- * @param The topology for the test setup.
- * @return command.
- */
 struct GNUNET_TESTING_Command
 GNUNET_TRANSPORT_cmd_backchannel_check (const char *label,
                                         const char *start_peer_label,
diff --git a/src/transport/transport_api_cmd_connecting_peers.c b/src/transport/transport_api_cmd_connecting_peers.c
index 8aba290c3..5513e0d6c 100644
--- a/src/transport/transport_api_cmd_connecting_peers.c
+++ b/src/transport/transport_api_cmd_connecting_peers.c
@@ -220,17 +220,6 @@ connect_peers_traits (void *cls,
 }
 
 
-/**
- * Create command
- *
- * @param label name for command
- * @param start_peer_label Label of the cmd to start a peer.
- * @param create_peer_label Label of the cmd which started the test system.
- * @param num Number globally identifying the node.
- * @param The topology for the test setup.
- * @param additional_connects Number of additional connects this cmd will wait for not triggered by this cmd.
- * @return command.
- */
 struct GNUNET_TESTING_Command
 GNUNET_TRANSPORT_cmd_connect_peers (const char *label,
                                     const char *start_peer_label,
diff --git a/src/transport/transport_api_core.c b/src/transport/transport_api_core.c
index 0ffaeb444..12612de09 100644
--- a/src/transport/transport_api_core.c
+++ b/src/transport/transport_api_core.c
@@ -713,7 +713,7 @@ handle_recv (void *cls, const struct InboundMessage *im)
  * Function we use for handling incoming set quota messages.
  *
  * @param cls closure, a `struct GNUNET_TRANSPORT_CoreHandle *`
- * @param msg message received
+ * @param qm message received
  */
 static void
 handle_set_quota (void *cls, const struct QuotaSetMessage *qm)
-- 
cgit v1.2.3