Correct various function comment headers

This commit refines function comment headers for improved accuracy
and consistency. Key changes include:

- Corrected parameter/return descriptions (e.g., `logtime`, `__daemon`).
- Added missing and removed incorrect parameter documentation (e.g.,
  `tcp_vu_sock_recv`, `ndp`).
- Standardized comments to the `/** ... */` style for functions
  like `udp_flow_close` and `ns_enter`.
- Ensured function names in comments consistently use `()`.
- Addressed minor typos and updated comments for renamed functions.

Signed-off-by: Laurent Vivier <lvivier@redhat.com>
Signed-off-by: Stefano Brivio <sbrivio@redhat.com>

13 files changed, 32 insertions, 28 deletions

diff --git a/conf.c b/conf.c
index a6d7e22..f4c8ca2 100644
--- a/conf.c
+++ b/conf.c
@@ -1358,7 +1358,7 @@ static void conf_open_files(struct ctx *c)
 }
 
 /**
- * parse_mac - Parse a MAC address from a string
+ * parse_mac() - Parse a MAC address from a string
  * @mac:	Binary MAC address, initialised on success
  * @str:	String to parse
  *
diff --git a/flow.c b/flow.c
index 6a5c8aa..cc05033 100644
--- a/flow.c
+++ b/flow.c
@@ -480,7 +480,9 @@ struct flowside *flow_target(const struct ctx *c, union flow *flow,
 /**
  * flow_set_type() - Set type and move to TYPED
  * @flow:	Flow to change state
- * @pif:	pif of the initiating side
+ * @type:	New flow type to assign
+ *
+ * Return: pointer to the modified flow structure.
  */
 union flow *flow_set_type(union flow *flow, enum flow_type type)
 {
diff --git a/log.c b/log.c
index 5d7d76f..33b89fc 100644
--- a/log.c
+++ b/log.c
@@ -54,7 +54,8 @@ bool		log_stderr = true;	/* Not daemonised, no shell spawned */
  * logtime() - Get the current time for logging purposes
  * @ts:		Buffer into which to store the timestamp
  *
- * Return: pointer to @now, or NULL if there was an error retrieving the time
+ * Return: pointer to @ts on success, or NULL if there was
+ *         an error retrieving the time
  */
 static const struct timespec *logtime(struct timespec *ts)
 {
diff --git a/ndp.c b/ndp.c
index b664034..3e15494 100644
--- a/ndp.c
+++ b/ndp.c
@@ -335,7 +335,6 @@ static void ndp_ra(const struct ctx *c, const struct in6_addr *dst)
 /**
  * ndp() - Check for NDP solicitations, reply as needed
  * @c:		Execution context
- * @ih:		ICMPv6 header
  * @saddr:	Source IPv6 address
  * @p:		Packet pool
  *
diff --git a/netlink.c b/netlink.c
index a052504..ee9325a 100644
--- a/netlink.c
+++ b/netlink.c
@@ -1024,7 +1024,6 @@ int nl_link_get_mac(int s, unsigned int ifi, void *mac)
 /**
  * nl_link_set_mac() - Set link MAC address
  * @s:		Netlink socket
- * @ns:		Use netlink socket in namespace
  * @ifi:	Interface index
  * @mac:	MAC address to set
  *
diff --git a/pasta.c b/pasta.c
index 017fa32..c207692 100644
--- a/pasta.c
+++ b/pasta.c
@@ -57,15 +57,13 @@ int pasta_child_pid;
 
 /**
  * pasta_child_handler() - Exit once shell exits (if we started it), reap clones
- * @signal:	Unused, handler deals with SIGCHLD only
+ * @signal:	 Signal number; this handler deals with SIGCHLD only
  */
 void pasta_child_handler(int signal)
 {
 	int errno_save = errno;
 	siginfo_t infop;
 
-	(void)signal;
-
 	if (signal != SIGCHLD)
 		return;
 
diff --git a/pcap.c b/pcap.c
index e95aa6f..46d11a2 100644
--- a/pcap.c
+++ b/pcap.c
@@ -52,8 +52,6 @@ struct pcap_pkthdr {
  * @iovcnt:	Number of buffers (@iov entries) in frame
  * @offset:	Byte offset of the L2 headers within @iov
  * @now:	Timestamp
- *
- * Returns: 0 on success, -errno on error writing to the file
  */
 static void pcap_frame(const struct iovec *iov, size_t iovcnt,
 		       size_t offset, const struct timespec *now)
@@ -113,10 +111,9 @@ void pcap_multiple(const struct iovec *iov, size_t frame_parts, unsigned int n,
 		pcap_frame(iov + i * frame_parts, frame_parts, offset, &now);
 }
 
-/*
- * pcap_iov - Write packet data described by an I/O vector
+/**
+ * pcap_iov() - Write packet data described by an I/O vector
  *		to a pcap file descriptor.
- *
  * @iov:	Pointer to the array of struct iovec describing the I/O vector
  *		containing packet data to write, including L2 header
  * @iovcnt:	Number of buffers (@iov entries)
diff --git a/tcp.c b/tcp.c
index 0ac298a..f43c1e2 100644
--- a/tcp.c
+++ b/tcp.c
@@ -456,7 +456,7 @@ int tcp_set_peek_offset(const struct tcp_tap_conn *conn, int offset)
 /**
  * tcp_conn_epoll_events() - epoll events mask for given connection state
  * @events:	Current connection events
- * @conn_flags	Connection flags
+ * @conn_flags:	Connection flags
  *
  * Return: epoll events mask corresponding to implied connection state
  */
@@ -1079,7 +1079,7 @@ out:
  * tcp_update_seqack_from_tap() - ACK number from tap and related flags/counters
  * @c:		Execution context
  * @conn:	Connection pointer
- * @seq		Current ACK sequence, host order
+ * @seq:	Current ACK sequence, host order
  */
 static void tcp_update_seqack_from_tap(const struct ctx *c,
 				       struct tcp_tap_conn *conn, uint32_t seq)
@@ -1103,7 +1103,7 @@ static void tcp_update_seqack_from_tap(const struct ctx *c,
  * @conn:	Connection pointer
  * @flags:	TCP flags: if not set, send segment only if ACK is due
  * @th:		TCP header to update
- * @data:	buffer to store TCP option
+ * @opts:	TCP option buffer (output parameter)
  * @optlen:	size of the TCP option buffer (output parameter)
  *
  * Return: < 0 error code on connection reset,
@@ -1238,7 +1238,7 @@ static void tcp_get_tap_ws(struct tcp_tap_conn *conn,
 /**
  * tcp_tap_window_update() - Process an updated window from tap side
  * @conn:	Connection pointer
- * @window:	Window value, host order, unscaled
+ * @wnd:	Window value, host order, unscaled
  */
 static void tcp_tap_window_update(struct tcp_tap_conn *conn, unsigned wnd)
 {
@@ -1261,6 +1261,8 @@ static void tcp_tap_window_update(struct tcp_tap_conn *conn, unsigned wnd)
  * tcp_init_seq() - Calculate initial sequence number according to RFC 6528
  * @hash:	Hash of connection details
  * @now:	Current timestamp
+ *
+ * Return: the calculated 32-bit initial sequence number.
  */
 static uint32_t tcp_init_seq(uint64_t hash, const struct timespec *now)
 {
diff --git a/tcp_buf.c b/tcp_buf.c
index 0530563..d1fca67 100644
--- a/tcp_buf.c
+++ b/tcp_buf.c
@@ -104,7 +104,7 @@ void tcp_sock_iov_init(const struct ctx *c)
 
 /**
  * tcp_revert_seq() - Revert affected conn->seq_to_tap after failed transmission
- * @ctx:	Execution context
+ * @c:		Execution context
  * @conns:	Array of connection pointers corresponding to queued frames
  * @frames:	Two-dimensional array containing queued frames with sub-iovs
  * @num_frames:	Number of entries in the two arrays to be compared
@@ -148,7 +148,7 @@ void tcp_payload_flush(const struct ctx *c)
 }
 
 /**
- * tcp_buf_fill_headers() - Fill 802.3, IP, TCP headers in pre-cooked buffers
+ * tcp_l2_buf_fill_headers() - Fill 802.3, IP, TCP headers in pre-cooked buffers
  * @conn:	Connection pointer
  * @iov:	Pointer to an array of iovec of TCP pre-cooked buffers
  * @check:	Checksum, if already known
diff --git a/tcp_vu.c b/tcp_vu.c
index 57587cc..f3914c7 100644
--- a/tcp_vu.c
+++ b/tcp_vu.c
@@ -176,8 +176,10 @@ int tcp_vu_send_flag(const struct ctx *c, struct tcp_tap_conn *conn, int flags)
  * @already_sent:	Number of bytes already sent
  * @fillsize:		Maximum bytes to fill in guest-side receiving window
  * @iov_cnt:		number of iov (output)
+ * @head_cnt:		Pointer to store the count of head iov entries (output)
  *
- * Return: Number of iov entries used to store the data or negative error code
+ * Return: number of bytes received from the socket, or a negative error code
+ * on failure.
  */
 static ssize_t tcp_vu_sock_recv(const struct ctx *c,
 				const struct tcp_tap_conn *conn, bool v6,
diff --git a/udp.c b/udp.c
index ca28b37..65a52e0 100644
--- a/udp.c
+++ b/udp.c
@@ -473,7 +473,7 @@ static void udp_send_tap_icmp6(const struct ctx *c,
 /**
  * udp_pktinfo() - Retrieve packet destination address from cmsg
  * @msg:	msghdr into which message has been received
- * @dst:	(Local) destination address of message in @mh (output)
+ * @dst:	(Local) destination address of message in @msg (output)
  *
  * Return: 0 on success, -1 if the information was missing (@dst is set to
  *         inany_any6).
@@ -736,7 +736,7 @@ static int udp_peek_addr(int s, union sockaddr_inany *src,
  * udp_sock_recv() - Receive datagrams from a socket
  * @c:		Execution context
  * @s:		Socket to receive from
- * @mmh		mmsghdr array to receive into
+ * @mmh:	mmsghdr array to receive into
  * @n:		Maximum number of datagrams to receive
  *
  * Return: Number of datagrams received
diff --git a/udp_flow.c b/udp_flow.c
index 4c6b3c2..cef3fb5 100644
--- a/udp_flow.c
+++ b/udp_flow.c
@@ -36,7 +36,7 @@ struct udp_flow *udp_at_sidx(flow_sidx_t sidx)
 	return &flow->udp;
 }
 
-/*
+/**
  * udp_flow_close() - Close and clean up UDP flow
  * @c:		Execution context
  * @uflow:	UDP flow
@@ -126,7 +126,8 @@ static int udp_flow_sock(const struct ctx *c,
  * @flow:	Initiated flow
  * @now:	Timestamp
  *
- * Return: UDP specific flow, if successful, NULL on failure
+ * Return: sidx for the target side of the new UDP flow, or FLOW_SIDX_NONE
+ *         on failure.
  *
  * #syscalls getsockname
  */
diff --git a/util.c b/util.c
index f5497d4..7b245cc 100644
--- a/util.c
+++ b/util.c
@@ -364,7 +364,7 @@ void bitmap_or(uint8_t *dst, size_t size, const uint8_t *a, const uint8_t *b)
 		dst[i] = a[i] | b[i];
 }
 
-/*
+/**
  * ns_enter() - Enter configured user (unless already joined) and network ns
  * @c:		Execution context
  *
@@ -499,7 +499,8 @@ int output_file_open(const char *path, int flags)
  * @pidfile_fd:	Open PID file descriptor
  * @devnull_fd:	Open file descriptor for /dev/null
  *
- * Return: child PID on success, won't return on failure
+ * Return: 0 in the child process on success. The parent process exits.
+ * 	   Does not return in either process on failure (calls _exit).
  */
 int __daemon(int pidfile_fd, int devnull_fd)
 {
@@ -607,7 +608,8 @@ int do_clone(int (*fn)(void *), char *stack_area, size_t stack_size, int flags,
 #endif
 }
 
-/* write_all_buf() - write all of a buffer to an fd
+/**
+ * write_all_buf() - write all of a buffer to an fd
  * @fd:		File descriptor
  * @buf:	Pointer to base of buffer
  * @len:	Length of buffer
@@ -637,7 +639,8 @@ int write_all_buf(int fd, const void *buf, size_t len)
 	return 0;
 }
 
-/* write_remainder() - write the tail of an IO vector to an fd
+/**
+ * write_remainder() - write the tail of an IO vector to an fd
  * @fd:		File descriptor
  * @iov:	IO vector
  * @iovcnt:	Number of entries in @iov