linux-kernel - [PATCH v3 1/8] x86/tsc: Fix major kernel-doc warnings for tsc.c

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20240201010453.2212371-2-peter.hilber@opensynergy.com>
Date: Thu,  1 Feb 2024 02:04:46 +0100
From: Peter Hilber <peter.hilber@...nsynergy.com>
To: linux-kernel@...r.kernel.org
Cc: Peter Hilber <peter.hilber@...nsynergy.com>,
	Simon Horman <horms@...nel.org>,
	"D, Lakshmi Sowjanya" <lakshmi.sowjanya.d@...el.com>,
	Thomas Gleixner <tglx@...utronix.de>,
	jstultz@...gle.com,
	giometti@...eenne.com,
	corbet@....net,
	"Dong, Eddie" <eddie.dong@...el.com>,
	"Hall, Christopher S" <christopher.s.hall@...el.com>,
	Andy Shevchenko <andriy.shevchenko@...ux.intel.com>,
	x86@...nel.org,
	Ingo Molnar <mingo@...hat.com>,
	Borislav Petkov <bp@...en8.de>,
	Dave Hansen <dave.hansen@...ux.intel.com>,
	"H. Peter Anvin" <hpa@...or.com>
Subject: [PATCH v3 1/8] x86/tsc: Fix major kernel-doc warnings for tsc.c

Fix the kernel-doc warnings which show up with default arguments for tsc.c:

	$ ./scripts/kernel-doc arch/x86/kernel/tsc.c >/dev/null
	arch/x86/kernel/tsc.c:1339: warning: Excess function parameter 'cycles' description in 'convert_art_ns_to_tsc'
	arch/x86/kernel/tsc.c:1339: warning: Excess function parameter 'cs' description in 'convert_art_ns_to_tsc'
	arch/x86/kernel/tsc.c:1373: warning: Function parameter or struct member 'work' not described in 'tsc_refine_calibration_work'

The first two warnings stem from members of the convert_art_ns_to_tsc()
return type (struct system_counterval_t). For convert_art_ns_to_tsc(),
the return type members are documented like parameters.

Since these members are already documented with the struct
system_counterval_t definition, remove the redundant documentation for
convert_art_ns_to_tsc(). This resolves the first two warnings.

Fix the third warning by appending a ':' instead of a '-' to the '@...k'
documentation parameter.

Suggested-by: Simon Horman <horms@...nel.org>
Signed-off-by: Peter Hilber <peter.hilber@...nsynergy.com>
---

Notes:
    v3: Added on suggestion of Simon Horman.

 arch/x86/kernel/tsc.c | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/arch/x86/kernel/tsc.c b/arch/x86/kernel/tsc.c
index d45084c6a15e..42328f9653c1 100644
--- a/arch/x86/kernel/tsc.c
+++ b/arch/x86/kernel/tsc.c
@@ -1329,10 +1329,6 @@ EXPORT_SYMBOL(convert_art_to_tsc);
  * Return:
  * struct system_counterval_t - system counter value with the pointer to the
  *	corresponding clocksource
- *	@cycles:	System counter value
- *	@cs:		Clocksource corresponding to system counter value. Used
- *			by timekeeping code to verify comparability of two cycle
- *			values.
  */
 
 struct system_counterval_t convert_art_ns_to_tsc(u64 art_ns)
@@ -1357,7 +1353,7 @@ static void tsc_refine_calibration_work(struct work_struct *work);
 static DECLARE_DELAYED_WORK(tsc_irqwork, tsc_refine_calibration_work);
 /**
  * tsc_refine_calibration_work - Further refine tsc freq calibration
- * @work - ignored.
+ * @work: ignored.
  *
  * This functions uses delayed work over a period of a
  * second to further refine the TSC freq value. Since this is
-- 
2.40.1