[PATCH 1/2] ARM: vexpress/spc: Fix doxygen comments

[PATCH 1/2] ARM: vexpress/spc: Fix doxygen comments

[Sudeep Holla]

Kbuild bot reported the following doxygen build warning:

  |  arch/arm/mach-versatile/spc.c:231: warning: This comment starts with
  |		'/**', but isn't a kernel-doc comment.
  |		Refer Documentation/doc-guide/kernel-doc.rst
  |  		* ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)

Fix the issue by dropping the parameters specified in the kernel doc.

Cc: Liviu Dudau <liviu.dudau@arm.com>
Cc: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
Reported-by: kernel test robot <lkp@intel.com>
Link: https://lore.kernel.org/linux-doc/202204031026.4ogKxt89-lkp@intel.com
Signed-off-by: Sudeep Holla <sudeep.holla@arm.com>
---
 arch/arm/mach-vexpress/spc.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/arch/arm/mach-vexpress/spc.c b/arch/arm/mach-vexpress/spc.c
index 1c6500c4e6a1..8f99d47d4b89 100644
--- a/arch/arm/mach-vexpress/spc.c
+++ b/arch/arm/mach-vexpress/spc.c
@@ -228,7 +228,7 @@ static u32 standbywfi_cpu_mask(u32 cpu, u32 cluster)
 }
 
 /**
- * ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
+ * ve_spc_cpu_in_wfi()
  *
  * @cpu: mpidr[7:0] bitfield describing CPU affinity level within cluster
  * @cluster: mpidr[15:8] bitfield describing cluster affinity level
-- 
2.35.1

[PATCH 2/2] ARM: vexpress/spc: Fix all the doxygen build warnings

[Sudeep Holla]

There are more doxygen build warnings as below than the ones reported
by kernel test robot recently.

  |  arch/arm/mach-vexpress/spc.c:125: warning: missing initial short description on line:
  |   * ve_spc_global_wakeup_irq()
  |  arch/arm/mach-vexpress/spc.c:131: warning: contents before sections
  |  arch/arm/mach-vexpress/spc.c:148: warning: missing initial short description on line:
  |   * ve_spc_cpu_wakeup_irq()
  |  arch/arm/mach-vexpress/spc.c:154: warning: contents before sections
  |  arch/arm/mach-vexpress/spc.c:203: warning: missing initial short description on line:
  |   * ve_spc_powerdown()
  |  arch/arm/mach-vexpress/spc.c:209: warning: contents before sections
  |  arch/arm/mach-vexpress/spc.c:231: warning: missing initial short description on line:
  |   * ve_spc_cpu_in_wfi()
  |  7 warnings

Fix all the warnings.

Cc: Liviu Dudau <liviu.dudau@arm.com>
Cc: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
Signed-off-by: Sudeep Holla <sudeep.holla@arm.com>
---
 arch/arm/mach-vexpress/spc.c | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/arch/arm/mach-vexpress/spc.c b/arch/arm/mach-vexpress/spc.c
index 8f99d47d4b89..6e6985e756af 100644
--- a/arch/arm/mach-vexpress/spc.c
+++ b/arch/arm/mach-vexpress/spc.c
@@ -122,13 +122,13 @@ static inline bool cluster_is_a15(u32 cluster)
 }
 
 /**
- * ve_spc_global_wakeup_irq()
+ * ve_spc_global_wakeup_irq() - sets/clears global wakeup IRQs
+ *
+ * @set: if true, global wake-up IRQs are set, if false they are cleared
  *
  * Function to set/clear global wakeup IRQs. Not protected by locking since
  * it might be used in code paths where normal cacheable locks are not
  * working. Locking must be provided by the caller to ensure atomicity.
- *
- * @set: if true, global wake-up IRQs are set, if false they are cleared
  */
 void ve_spc_global_wakeup_irq(bool set)
 {
@@ -145,15 +145,15 @@ void ve_spc_global_wakeup_irq(bool set)
 }
 
 /**
- * ve_spc_cpu_wakeup_irq()
- *
- * Function to set/clear per-CPU wake-up IRQs. Not protected by locking since
- * it might be used in code paths where normal cacheable locks are not
- * working. Locking must be provided by the caller to ensure atomicity.
+ * ve_spc_cpu_wakeup_irq() - sets/clears per-CPU wake-up IRQs
  *
  * @cluster: mpidr[15:8] bitfield describing cluster affinity level
  * @cpu: mpidr[7:0] bitfield describing cpu affinity level
  * @set: if true, wake-up IRQs are set, if false they are cleared
+ *
+ * Function to set/clear per-CPU wake-up IRQs. Not protected by locking since
+ * it might be used in code paths where normal cacheable locks are not
+ * working. Locking must be provided by the caller to ensure atomicity.
  */
 void ve_spc_cpu_wakeup_irq(u32 cluster, u32 cpu, bool set)
 {
@@ -200,14 +200,14 @@ void ve_spc_set_resume_addr(u32 cluster, u32 cpu, u32 addr)
 }
 
 /**
- * ve_spc_powerdown()
+ * ve_spc_powerdown() - enables/disables cluster powerdown
+ *
+ * @cluster: mpidr[15:8] bitfield describing cluster affinity level
+ * @enable: if true enables powerdown, if false disables it
  *
  * Function to enable/disable cluster powerdown. Not protected by locking
  * since it might be used in code paths where normal cacheable locks are not
  * working. Locking must be provided by the caller to ensure atomicity.
- *
- * @cluster: mpidr[15:8] bitfield describing cluster affinity level
- * @enable: if true enables powerdown, if false disables it
  */
 void ve_spc_powerdown(u32 cluster, bool enable)
 {
@@ -228,7 +228,7 @@ static u32 standbywfi_cpu_mask(u32 cpu, u32 cluster)
 }
 
 /**
- * ve_spc_cpu_in_wfi()
+ * ve_spc_cpu_in_wfi() - Checks if the specified CPU is in WFI or not
  *
  * @cpu: mpidr[7:0] bitfield describing CPU affinity level within cluster
  * @cluster: mpidr[15:8] bitfield describing cluster affinity level
-- 
2.35.1

Re: [PATCH 1/2] ARM: vexpress/spc: Fix doxygen comments

[Randy Dunlap]

Hi--

On 4/4/22 06:02, Sudeep Holla wrote:
> Kbuild bot reported the following doxygen build warning:
> 
>   |  arch/arm/mach-versatile/spc.c:231: warning: This comment starts with
>   |		'/**', but isn't a kernel-doc comment.
>   |		Refer Documentation/doc-guide/kernel-doc.rst
>   |  		* ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
> 
> Fix the issue by dropping the parameters specified in the kernel doc.
> 
> Cc: Liviu Dudau <liviu.dudau@arm.com>
> Cc: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
> Reported-by: kernel test robot <lkp@intel.com>
> Link: https://lore.kernel.org/linux-doc/202204031026.4ogKxt89-lkp@intel.com
> Signed-off-by: Sudeep Holla <sudeep.holla@arm.com>
> ---
>  arch/arm/mach-vexpress/spc.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/arch/arm/mach-vexpress/spc.c b/arch/arm/mach-vexpress/spc.c
> index 1c6500c4e6a1..8f99d47d4b89 100644
> --- a/arch/arm/mach-vexpress/spc.c
> +++ b/arch/arm/mach-vexpress/spc.c
> @@ -228,7 +228,7 @@ static u32 standbywfi_cpu_mask(u32 cpu, u32 cluster)
>  }
>  
>  /**
> - * ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
> + * ve_spc_cpu_in_wfi()

This line still needs a "function short description," e.g.

+ * ve_spc_cpu_in_wfi() - fooble the barfloppity

similar to what you did in patch 2/2.

>   *
>   * @cpu: mpidr[7:0] bitfield describing CPU affinity level within cluster
>   * @cluster: mpidr[15:8] bitfield describing cluster affinity level

and I would s/doxygen/kernel-doc/ for both patches.

thanks.
-- 
~Randy

Re: [PATCH 1/2] ARM: vexpress/spc: Fix doxygen comments

[Sudeep Holla]

Hi Randy,

On Mon, Apr 04, 2022 at 05:21:39PM -0700, Randy Dunlap wrote:
> Hi--
> 
> On 4/4/22 06:02, Sudeep Holla wrote:
> > Kbuild bot reported the following doxygen build warning:
> > 
> >   |  arch/arm/mach-versatile/spc.c:231: warning: This comment starts with
> >   |		'/**', but isn't a kernel-doc comment.
> >   |		Refer Documentation/doc-guide/kernel-doc.rst
> >   |  		* ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
> > 
> > Fix the issue by dropping the parameters specified in the kernel doc.
> > 
> > Cc: Liviu Dudau <liviu.dudau@arm.com>
> > Cc: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
> > Reported-by: kernel test robot <lkp@intel.com>
> > Link: https://lore.kernel.org/linux-doc/202204031026.4ogKxt89-lkp@intel.com
> > Signed-off-by: Sudeep Holla <sudeep.holla@arm.com>
> > ---
> >  arch/arm/mach-vexpress/spc.c | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/arch/arm/mach-vexpress/spc.c b/arch/arm/mach-vexpress/spc.c
> > index 1c6500c4e6a1..8f99d47d4b89 100644
> > --- a/arch/arm/mach-vexpress/spc.c
> > +++ b/arch/arm/mach-vexpress/spc.c
> > @@ -228,7 +228,7 @@ static u32 standbywfi_cpu_mask(u32 cpu, u32 cluster)
> >  }
> >  
> >  /**
> > - * ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
> > + * ve_spc_cpu_in_wfi()
> 
> This line still needs a "function short description," e.g.
> 
> + * ve_spc_cpu_in_wfi() - fooble the barfloppity
> 
> similar to what you did in patch 2/2.

I did this intentionally, I can move only this from the other patch.
Since I saw few others w/o description, I addressed all at once in the
second patch and just remove warning reported in this patch. I am fine
either way.

> 
> >   *
> >   * @cpu: mpidr[7:0] bitfield describing CPU affinity level within cluster
> >   * @cluster: mpidr[15:8] bitfield describing cluster affinity level
> 
> and I would s/doxygen/kernel-doc/ for both patches.
> 

Sure will do.

-- 
Regards,
Sudeep

Re: [PATCH 1/2] ARM: vexpress/spc: Fix doxygen comments

[Randy Dunlap]

On 4/5/22 07:08, Sudeep Holla wrote:
> Hi Randy,
> 
> On Mon, Apr 04, 2022 at 05:21:39PM -0700, Randy Dunlap wrote:
>> Hi--
>>
>> On 4/4/22 06:02, Sudeep Holla wrote:
>>> Kbuild bot reported the following doxygen build warning:
>>>
>>>   |  arch/arm/mach-versatile/spc.c:231: warning: This comment starts with
>>>   |		'/**', but isn't a kernel-doc comment.
>>>   |		Refer Documentation/doc-guide/kernel-doc.rst
>>>   |  		* ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
>>>
>>> Fix the issue by dropping the parameters specified in the kernel doc.
>>>
>>> Cc: Liviu Dudau <liviu.dudau@arm.com>
>>> Cc: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
>>> Reported-by: kernel test robot <lkp@intel.com>
>>> Link: https://lore.kernel.org/linux-doc/202204031026.4ogKxt89-lkp@intel.com
>>> Signed-off-by: Sudeep Holla <sudeep.holla@arm.com>
>>> ---
>>>  arch/arm/mach-vexpress/spc.c | 2 +-
>>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>>
>>> diff --git a/arch/arm/mach-vexpress/spc.c b/arch/arm/mach-vexpress/spc.c
>>> index 1c6500c4e6a1..8f99d47d4b89 100644
>>> --- a/arch/arm/mach-vexpress/spc.c
>>> +++ b/arch/arm/mach-vexpress/spc.c
>>> @@ -228,7 +228,7 @@ static u32 standbywfi_cpu_mask(u32 cpu, u32 cluster)
>>>  }
>>>  
>>>  /**
>>> - * ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
>>> + * ve_spc_cpu_in_wfi()
>>
>> This line still needs a "function short description," e.g.
>>
>> + * ve_spc_cpu_in_wfi() - fooble the barfloppity
>>
>> similar to what you did in patch 2/2.
> 
> I did this intentionally, I can move only this from the other patch.
> Since I saw few others w/o description, I addressed all at once in the
> second patch and just remove warning reported in this patch. I am fine
> either way.

Oh, my bad. I didn't notice that it was the same function in
both patches.
So no problem there.

>>
>>>   *
>>>   * @cpu: mpidr[7:0] bitfield describing CPU affinity level within cluster
>>>   * @cluster: mpidr[15:8] bitfield describing cluster affinity level
>>
>> and I would s/doxygen/kernel-doc/ for both patches.
>>
> 
> Sure will do.
> 

thanks.
-- 
~Randy

Re: [PATCH 1/2] ARM: vexpress/spc: Fix doxygen comments

[Sudeep Holla]

On Mon, 4 Apr 2022 14:02:06 +0100, Sudeep Holla wrote:
> Kbuild bot reported the following doxygen build warning:
> 
>   |  arch/arm/mach-versatile/spc.c:231: warning: This comment starts with
>   |		'/**', but isn't a kernel-doc comment.
>   |		Refer Documentation/doc-guide/kernel-doc.rst
>   |  		* ve_spc_cpu_in_wfi(u32 cpu, u32 cluster)
> 
> [...]


Applied to sudeep.holla/linux (fixes/vexpress) with
s/doxygen/kernel-doc/ as suggested by Randy

[1/2] ARM: vexpress/spc: Fix kernel-doc build warning for ve_spc_cpu_in_wfi
      https://git.kernel.org/sudeep.holla/c/5063b7a80e
[2/2] ARM: vexpress/spc: Fix all the kernel-doc build warnings
      https://git.kernel.org/sudeep.holla/c/42a997f0bd

--
Regards,
Sudeep