From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: passt.top; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=R9zbM5it; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by passt.top (Postfix) with ESMTPS id 7F9305A027C for ; Mon, 19 May 2025 10:53:03 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1747644782; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=eWIGP9tY17sjKolVyWDnuIplv4uvhmqvjLZoi8vRoGw=; b=R9zbM5itwZyefPY6pc7N2S0Ehd3/APbHgcLj5nWv+csDZu8eavYkrwhjlivICgTwAqkaO1 lFAYQm64/i700sFqUZoEv+NpDInZ6cTzBWZKfaSY1m3hxpK661c/39VCBjcGQHzNxn1NpV ZyINMtELNdA/jGw7gM0W8qJzlIwmN/o= Received: from mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-663-Czun9LjcOpyWsAYwiRzpNw-1; Mon, 19 May 2025 04:53:00 -0400 X-MC-Unique: Czun9LjcOpyWsAYwiRzpNw-1 X-Mimecast-MFC-AGG-ID: Czun9LjcOpyWsAYwiRzpNw_1747644780 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D594619560AA for ; Mon, 19 May 2025 08:52:59 +0000 (UTC) Received: from lenovo-t14s.redhat.com (unknown [10.44.33.64]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id AD57919560AA; Mon, 19 May 2025 08:52:58 +0000 (UTC) From: Laurent Vivier To: passt-dev@passt.top Subject: [PATCH] Correct various function comment headers Date: Mon, 19 May 2025 10:52:56 +0200 Message-ID: <20250519085256.44985-1-lvivier@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: WeYUEU81nxDlIgomcK0rykKyUoSc2LvAMqqQlautROY_1747644780 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit content-type: text/plain; charset="US-ASCII"; x-default=true Message-ID-Hash: T4XXDI2NAUH6775KEGTDCEGR2LOGKXRM X-Message-ID-Hash: T4XXDI2NAUH6775KEGTDCEGR2LOGKXRM X-MailFrom: lvivier@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Laurent Vivier X-Mailman-Version: 3.3.8 Precedence: list List-Id: Development discussion and patches for passt Archived-At: Archived-At: List-Archive: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- conf.c | 2 +- flow.c | 4 +++- log.c | 3 ++- ndp.c | 1 - netlink.c | 1 - pasta.c | 4 +--- pcap.c | 7 ++----- tcp.c | 10 ++++++---- tcp_buf.c | 4 ++-- tcp_vu.c | 4 +++- udp.c | 4 ++-- udp_flow.c | 5 +++-- util.c | 11 +++++++---- 13 files changed, 32 insertions(+), 28 deletions(-) diff --git a/conf.c b/conf.c index a6d7e22a860c..f4c8ca25c87e 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 6a5c8aa439c2..cc050339c9c4 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 5d7d76f68b2e..33b89fc14574 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 b664034b00b1..3e1549456839 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 a0525047e898..ee9325a054a2 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 017fa3224c65..c20769211d9e 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 e95aa6fe29a6..46d11a2a6daa 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 0ac298a74125..f43c1e27c112 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 05305636b503..d1fca676c9a7 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 57587cc73a63..f3914c7c2195 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 ca28b37c142d..65a52e0755c0 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 4c6b3c2ca8da..cef3fb588bbe 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 f5497d4634dc..7b245ccc01f9 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 -- 2.49.0