Received-SPF: pass (google.com: domain of linux-kernel+bounces-47635-linux.lists.archive=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3;
Message-ID: <2b482c41-4eb0-4a49-a425-469b05d63018@infradead.org>
Date: Wed, 31 Jan 2024 20:52:11 -0800
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH v3 1/8] x86/tsc: Fix major kernel-doc warnings for tsc.c
Content-Language: en-US
To: Peter Hilber <peter.hilber@opensynergy.com>, linux-kernel@vger.kernel.org
Cc: Simon Horman <horms@kernel.org>,
 "D, Lakshmi Sowjanya" <lakshmi.sowjanya.d@intel.com>,
 Thomas Gleixner <tglx@linutronix.de>, jstultz@google.com,
 giometti@enneenne.com, corbet@lwn.net, "Dong, Eddie" <eddie.dong@intel.com>,
 "Hall, Christopher S" <christopher.s.hall@intel.com>,
 Andy Shevchenko <andriy.shevchenko@linux.intel.com>, x86@kernel.org,
 Ingo Molnar <mingo@redhat.com>, Borislav Petkov <bp@alien8.de>,
 Dave Hansen <dave.hansen@linux.intel.com>, "H. Peter Anvin" <hpa@zytor.com>
References: <20240201010453.2212371-1-peter.hilber@opensynergy.com>
 <20240201010453.2212371-2-peter.hilber@opensynergy.com>
From: Randy Dunlap <rdunlap@infradead.org>
In-Reply-To: <20240201010453.2212371-2-peter.hilber@opensynergy.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit


On 1/31/24 17:04, Peter Hilber wrote:
> 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 '@work'
> documentation parameter.
> 
> Suggested-by: Simon Horman <horms@kernel.org>
> Signed-off-by: Peter Hilber <peter.hilber@opensynergy.com>

Hi,
or this way:

https://lore.kernel.org/lkml/20231221033620.32379-1-rdunlap@infradead.org/

Thanks.

> ---
> 
> 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

-- 
#Randy