From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from picard.linux.it (picard.linux.it [213.254.12.146]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 2DA67C79FA1 for ; Fri, 11 Sep 2026 07:04:50 +0000 (UTC) Received: from picard.linux.it (localhost [IPv6:::1]) by picard.linux.it (Postfix) with ESMTP id 425633E72D0 for ; Fri, 11 Sep 2026 09:04:48 +0200 (CEST) Received: from in-4.smtp.seeweb.it (in-4.smtp.seeweb.it [217.194.8.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1)) (No client certificate requested) by picard.linux.it (Postfix) with ESMTPS id 2B8F43E2EFF for ; Fri, 11 Sep 2026 09:04:31 +0200 (CEST) Received: from smtp-out2.suse.de (smtp-out2.suse.de [195.135.223.131]) (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 in-4.smtp.seeweb.it (Postfix) with ESMTPS id 7D94D1000A3A for ; Fri, 11 Sep 2026 09:04:30 +0200 (CEST) Received: from imap1.dmz-prg2.suse.org (unknown [10.150.64.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by smtp-out2.suse.de (Postfix) with ESMTPS id B32C31FEEC; Fri, 11 Sep 2026 07:04:21 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1789110265; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=gPe2gUODs4Tvvza2GwLQa/hniu77QrPo2514OQqQFzI=; b=n3MR+Cwu8vQSHv1MjCDEDuXLvVklMeI8VqjbsOoCAWL1zmzPIBTdS/fTSfz5EFp19VsreV 9eXHanVmoA+m9bQeX8td++NW5ItF2Gnc7llG63xJNAnmYot0NgOX3dxaVChQuvw30Pmi6E id0RjtalhubZ3HWH/Dlkd46lj48fUm4= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1789110265; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=gPe2gUODs4Tvvza2GwLQa/hniu77QrPo2514OQqQFzI=; b=MeQdM/gixSilAU6FoEtCCdDpxdhjYgRh7jb6KtFVTJG3iwzsmUc6dQw2dYk1Rch5ngwJWJ vx4izIHhh13W+OAA== Authentication-Results: smtp-out2.suse.de; none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_rsa; t=1789110261; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=gPe2gUODs4Tvvza2GwLQa/hniu77QrPo2514OQqQFzI=; b=vrhmmtEzO5WSTHD3UTvQ8eUnZXCqapjnTHEQmbxvaHPRMtCO7BrgJo/ujYfJwo5VfCQt6l m3CPRSOzx8k/iiqfWaFf3+KXjPmm1JDhoY4p+1i7+FZ6jO/ZDl0MqdVXGCKiuc+0KiGrCr y/vqSxaY+0/+XEf8Z52XCgU7L+qc8KY= DKIM-Signature: v=1; a=ed25519-sha256; c=relaxed/relaxed; d=suse.de; s=susede2_ed25519; t=1789110261; h=from:from:reply-to:date:date:message-id:message-id:to:to:cc:cc: mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=gPe2gUODs4Tvvza2GwLQa/hniu77QrPo2514OQqQFzI=; b=7rx6x33g4dnNnN0O409WcJXQq60K0D6Oa1gKgUJTdChYIxJzQ4s1t5bjer6QOhLWFKQZqd hINu/dbnAlTznfDg== Received: from imap1.dmz-prg2.suse.org (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by imap1.dmz-prg2.suse.org (Postfix) with ESMTPS id 38ACB137CA; Fri, 11 Sep 2026 07:04:21 +0000 (UTC) Received: from dovecot-director2.suse.de ([2a07:de40:b281:106:10:150:64:167]) by imap1.dmz-prg2.suse.org with ESMTPSA id mAUpDPWno2qwLwAAD6G6ig (envelope-from ); Fri, 11 Sep 2026 07:04:21 +0000 From: Andrea Cervesato Date: Fri, 11 Sep 2026 09:04:20 +0200 MIME-Version: 1.0 Message-Id: <20260911-fix_documentation-v2-4-716b2613c477@suse.com> References: <20260911-fix_documentation-v2-0-716b2613c477@suse.com> In-Reply-To: <20260911-fix_documentation-v2-0-716b2613c477@suse.com> To: Linux Test Project X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=ed25519-sha256; t=1789110260; l=4775; i=andrea.cervesato@suse.com; s=20251210; h=from:subject:message-id; bh=nMIzlNce8FGFjfe1yWsdIE5gZ/5nzKgpuW4P5k7tl7g=; b=0RJZ+OCtX57FONFZUY84528RUsYEAjMh+Edk/a4MlG+RQcIPE64YbYIMKs605EuLlBDUKocZH DcMgMiTB/pZCBeemwYFCskocWdLamc+Wvu6z8TYwiqWI7jAr+dkWlxm X-Developer-Key: i=andrea.cervesato@suse.com; a=ed25519; pk=zKY+6GCauOiuHNZ//d8PQ/UL4jFCTKbXrzXAOQSLevI= X-Spamd-Result: default: False [-4.30 / 50.00]; BAYES_HAM(-3.00)[100.00%]; NEURAL_HAM_LONG(-1.00)[-1.000]; NEURAL_HAM_SHORT(-0.20)[-0.996]; MIME_GOOD(-0.10)[text/plain]; RCVD_VIA_SMTP_AUTH(0.00)[]; RCVD_TLS_ALL(0.00)[]; ARC_NA(0.00)[]; MIME_TRACE(0.00)[0:+]; DKIM_SIGNED(0.00)[suse.de:s=susede2_rsa,suse.de:s=susede2_ed25519]; TO_DN_ALL(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[3]; FROM_EQ_ENVFROM(0.00)[]; RCVD_COUNT_TWO(0.00)[2]; DBL_BLOCKED_OPENRESOLVER(0.00)[imap1.dmz-prg2.suse.org:helo, suse.cz:email, suse.com:mid, suse.com:email] X-Virus-Scanned: clamav-milter 1.0.9 at in-4.smtp.seeweb.it X-Virus-Status: Clean Subject: [LTP] [PATCH v2 4/9] include: Document assertion API macros X-BeenThere: ltp@lists.linux.it X-Mailman-Version: 2.1.29 Precedence: list List-Id: Linux Test Project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ltp-bounces+ltp=archiver.kernel.org@lists.linux.it Sender: "ltp" From: Andrea Cervesato Add kernel-doc comments for the public assertion macros in include/tst_assert.h to populate the Assertion section in the generated C API documentation. Signed-off-by: Andrea Cervesato Reviewed-by: Petr Vorel --- include/tst_assert.h | 85 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 56 insertions(+), 29 deletions(-) diff --git a/include/tst_assert.h b/include/tst_assert.h index dcb62dfea..e952f612f 100644 --- a/include/tst_assert.h +++ b/include/tst_assert.h @@ -7,58 +7,85 @@ #ifndef TST_ASSERT_H__ #define TST_ASSERT_H__ +/** + * TST_ASSERT_INT() - Asserts that integer value in file equals val. + * + * @path: Path to the file to check. + * @val: Expected integer value. + * + * Reads an integer from the file at path and compares it to val. + * Reports :c:enum:`TPASS ` on match, or + * :c:enum:`TFAIL ` on mismatch. + */ #define TST_ASSERT_INT(path, val) \ tst_assert_int(__FILE__, __LINE__, path, val) -/* - * Asserts that integer value stored in file pointed by path equals to the - * value passed to this function. This is mostly useful for asserting correct - * values in sysfs, procfs, etc. - */ void tst_assert_int(const char *file, const int lineno, const char *path, int val); +/** + * TST_ASSERT_FILE_INT() - Asserts that integer value for field in file equals val. + * + * @path: Path to the file to check. + * @prefix: Field name or line prefix preceding the integer value. + * @val: Expected integer value. + * + * Scans lines in path for prefix followed by an integer. + * Reports :c:enum:`TPASS ` on match, or + * :c:enum:`TFAIL ` on mismatch. + */ #define TST_ASSERT_FILE_INT(path, prefix, val) \ tst_assert_file_int(__FILE__, __LINE__, path, prefix, val) -/* - * Same as tst_assert_int() but for unsigned long. - */ -void tst_assert_ulong(const char *file, const int lineno, - const char *path, unsigned long val); +void tst_assert_file_int(const char *file, const int lineno, + const char *path, const char *prefix, int val); +/** + * TST_ASSERT_ULONG() - Asserts that unsigned long value in file equals val. + * + * @path: Path to the file to check. + * @val: Expected unsigned long value. + * + * Reads an unsigned long from the file at path and compares it to val. + * Reports :c:enum:`TPASS ` on match, or + * :c:enum:`TFAIL ` on mismatch. + */ #define TST_ASSERT_ULONG(path, val) \ tst_assert_ulong(__FILE__, __LINE__, path, val) -/* - * Asserts that integer value stored in the prefix field of file pointed by path - * equals to the value passed to this function. This is mostly useful for - * asserting correct field values in sysfs, procfs, etc. - */ - -void tst_assert_file_int(const char *file, const int lineno, - const char *path, const char *prefix, int val); - +void tst_assert_ulong(const char *file, const int lineno, + const char *path, unsigned long val); +/** + * TST_ASSERT_STR() - Asserts that string value in file equals val. + * + * @path: Path to the file to check. + * @val: Expected string value. + * + * Reads a whitespace-delimited string from path and compares it to val. + * Reports :c:enum:`TPASS ` on match, or + * :c:enum:`TFAIL ` on mismatch. + */ #define TST_ASSERT_STR(path, val) \ tst_assert_str(__FILE__, __LINE__, path, val) -/* - * Asserts that a string value stored in file pointed by path equals to the - * value passed to this function. This is mostly useful for asserting correct - * values in sysfs, procfs, etc. - */ void tst_assert_str(const char *file, const int lineno, const char *path, const char *val); +/** + * TST_ASSERT_FILE_STR() - Asserts that string value for field in file equals val. + * + * @path: Path to the file to check. + * @prefix: Field name or prefix preceding the string value. + * @val: Expected string value. + * + * Scans lines in path for prefix followed by ": " and a string value. + * Reports :c:enum:`TPASS ` on match, or + * :c:enum:`TFAIL ` on mismatch. + */ #define TST_ASSERT_FILE_STR(path, prefix, val) \ tst_assert_file_str(__FILE__, __LINE__, path, prefix, val) -/* - * Asserts that a string value stored in the prefix field of file pointed by path - * equals to the value passed to this function. This is mostly useful for - * asserting correct field values in sysfs, procfs, etc. - */ void tst_assert_file_str(const char *file, const int lineno, const char *path, const char *prefix, const char *val); -- 2.51.0 -- Mailing list info: https://lists.linux.it/listinfo/ltp