Re: [PATCH] x86: kernel: cpu: resctrl: Fix kernel-doc in pseudo_lock.c

[Reinette Chatre <reinette.chatre@intel.com>]

Hi Fabio,

Thank you very much for catching these. I am curious what your goal is 
because when I ran a kernel-doc check on the resctrl area there were 
many more warnings than are not addressed in this patch. Also, while 
this patch claims to fix the kernel-doc in pseudo_lock.c there seems to 
be a few more that are not addressed. Are you planning to submit more 
patches to do a cleanup of kernel-doc or are these the only ones 
bothering you for some reason?

Could you please fixup the subject to conform to this area:
"x86/resctrl: Fix kernel-doc in pseudo_lock.c"

For this subject to be accurate though it should fix all the kernel-doc 
warnings found in pseudo_lock.c - or if not it would be helpful to 
explain what the criteria for fixes are. I tested this by running:
$ scripts/kernel-doc -v -none arch/x86/kernel/cpu/resctrl/*

On 6/2/2021 3:23 PM, Fabio M. De Francesco wrote:
> Fixed sparse warnings about the descriptions of some function
> parameters.
> 
> Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> ---
>   arch/x86/kernel/cpu/resctrl/pseudo_lock.c | 4 +++-
>   1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
> index f6451abddb09..c3629db90570 100644
> --- a/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
> +++ b/arch/x86/kernel/cpu/resctrl/pseudo_lock.c
> @@ -520,7 +520,7 @@ static int pseudo_lock_fn(void *_rdtgrp)
>   
>   /**
>    * rdtgroup_monitor_in_progress - Test if monitoring in progress
> - * @r: resource group being queried
> + * @rdtgrp: resource group being queried
>    *
>    * Return: 1 if monitor groups have been created for this resource
>    * group, 0 otherwise.
> @@ -1140,6 +1140,8 @@ static int measure_l3_residency(void *_plr)
>   
>   /**
>    * pseudo_lock_measure_cycles - Trigger latency measure to pseudo-locked region
> + * @rdtgrp: resource group to which the pseudo-locked region belongs
> + * @sel: cache level selector

This is not correct. A more accurate description could be:
"select which measurement to perform on pseudo-locked region"

>    *
>    * The measurement of latency to access a pseudo-locked region should be
>    * done from a cpu that is associated with that pseudo-locked region.
> 

Reinette