[PATCH 0/2] kernel-doc and MAINTAINERS clean-up

[PATCH 0/2] kernel-doc and MAINTAINERS clean-up

[Lukas Bulwahn]

Roughly 900 warnings of about 21.000 kernel-doc warnings in the kernel tree
warn with 'cannot understand function prototype:', i.e., the kernel-doc parser
cannot parse the function's signature. The majority, about 600 cases of those,
are just struct definitions following the kernel-doc description. Further,
spot-check investigations suggest that the authors of the specific kernel-doc
descriptions simply were not aware that the general format for a kernel-doc
description for a structure requires to prefix the struct name with the keyword
'struct', as in 'struct struct_name - Brief description.'. Details on
kernel-doc are at the Link below.

Without the struct keyword, kernel-doc does not check if the kernel-doc
description fits to the actual struct definition in the source code.
Fortunately, in roughly a quarter of these cases, the kernel-doc description is
actually complete wrt. its corresponding struct definition. So, the trivial
change adding the struct keyword will allow us to keep the kernel-doc
descriptions more consistent for future changes, by checking for new kernel-doc
warnings.

Also, some of the files in ./include/ are not assigned to a specific
MAINTAINERS section and hence have no dedicated maintainer. So, if needed, the
files in ./include/ are also assigned to the fitting MAINTAINERS section, as I
need to identify whom to send the clean-up patch anyway.

Here is the change from this kernel-doc janitorial work in the ./include/
directory for MEMORY MANAGEMENT.

Andrew, please pick this clean-up patch series for mm.

Link: https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html


Lukas Bulwahn (2):
  MAINTAINERS: assign pagewalk.h to MEMORY MANAGEMENT
  pagewalk: prefix struct kernel-doc descriptions

 MAINTAINERS              | 1 +
 include/linux/pagewalk.h | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

-- 
2.17.1

[PATCH 1/2] MAINTAINERS: assign pagewalk.h to MEMORY MANAGEMENT

[Lukas Bulwahn]

Commit a520110e4a15 ("mm: split out a new pagewalk.h header from mm.h")
adds a new file in ./include/linux, but misses to update MAINTAINERS
accordingly. Hence, ./scripts/get_maintainers.pl ./include/linux/pagewalk.h
points only to lkml as general fallback for all files, whereas the original
./include/linux/mm.h clearly marks this file part of MEMORY MANAGEMENT.

Assign ./include/linux/pagewalk.h to MEMORY MANAGEMENT.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 728216e3919c..46a1eddbc3e4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11622,6 +11622,7 @@ F:	include/linux/gfp.h
 F:	include/linux/memory_hotplug.h
 F:	include/linux/mm.h
 F:	include/linux/mmzone.h
+F:	include/linux/pagewalk.h
 F:	include/linux/vmalloc.h
 F:	mm/
 
-- 
2.17.1

[PATCH 2/2] pagewalk: prefix struct kernel-doc descriptions

[Lukas Bulwahn]

The script './scripts/kernel-doc -none ./include/linux/pagewalk.h' reports:

  include/linux/pagewalk.h:37: warning: cannot understand function prototype: 'struct mm_walk_ops '
  include/linux/pagewalk.h:85: warning: cannot understand function prototype: 'struct mm_walk '

A kernel-doc description for a structure requires to prefix the struct name
with the keyword 'struct'. So, do that such that no further kernel-doc
warnings are reported for this file.

Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
 include/linux/pagewalk.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/include/linux/pagewalk.h b/include/linux/pagewalk.h
index b1cb6b753abb..ac7b38ad5903 100644
--- a/include/linux/pagewalk.h
+++ b/include/linux/pagewalk.h
@@ -7,7 +7,7 @@
 struct mm_walk;
 
 /**
- * mm_walk_ops - callbacks for walk_page_range
+ * struct mm_walk_ops - callbacks for walk_page_range
  * @pgd_entry:		if set, called for each non-empty PGD (top-level) entry
  * @p4d_entry:		if set, called for each non-empty P4D entry
  * @pud_entry:		if set, called for each non-empty PUD entry
@@ -71,7 +71,7 @@ enum page_walk_action {
 };
 
 /**
- * mm_walk - walk_page_range data
+ * struct mm_walk - walk_page_range data
  * @ops:	operation to call during the walk
  * @mm:		mm_struct representing the target process of page table walk
  * @pgd:	pointer to PGD; only valid with no_vma (otherwise set to NULL)
-- 
2.17.1

Re: [PATCH 1/2] MAINTAINERS: assign pagewalk.h to MEMORY MANAGEMENT

[Mike Rapoport]

On Mon, Mar 22, 2021 at 01:25:41PM +0100, Lukas Bulwahn wrote:
> Commit a520110e4a15 ("mm: split out a new pagewalk.h header from mm.h")
> adds a new file in ./include/linux, but misses to update MAINTAINERS
> accordingly. Hence, ./scripts/get_maintainers.pl ./include/linux/pagewalk.h
> points only to lkml as general fallback for all files, whereas the original
> ./include/linux/mm.h clearly marks this file part of MEMORY MANAGEMENT.
> 
> Assign ./include/linux/pagewalk.h to MEMORY MANAGEMENT.
> 
> Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
> ---
>  MAINTAINERS | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 728216e3919c..46a1eddbc3e4 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -11622,6 +11622,7 @@ F:	include/linux/gfp.h
>  F:	include/linux/memory_hotplug.h
>  F:	include/linux/mm.h
>  F:	include/linux/mmzone.h
> +F:	include/linux/pagewalk.h

I'd say that we miss all include/linux/page* here, not only pagewalk.h

>  F:	include/linux/vmalloc.h
>  F:	mm/
>  
> -- 
> 2.17.1
> 

-- 
Sincerely yours,
Mike.

[PATCH 0/2] kernel-doc and MAINTAINERS clean-up

[Lukas Bulwahn]

Roughly 900 warnings of about 21.000 kernel-doc warnings in the kernel tree
warn with 'cannot understand function prototype:', i.e., the kernel-doc parser
cannot parse the function's signature. The majority, about 600 cases of those,
are just struct definitions following the kernel-doc description. Further,
spot-check investigations suggest that the authors of the specific kernel-doc
descriptions simply were not aware that the general format for a kernel-doc
description for a structure requires to prefix the struct name with the keyword
'struct', as in 'struct struct_name - Brief description.'. Details on
kernel-doc are at the Link below.

Without the struct keyword, kernel-doc does not check if the kernel-doc
description fits to the actual struct definition in the source code.
Fortunately, in roughly a quarter of these cases, the kernel-doc description is
actually complete wrt. its corresponding struct definition. So, the trivial
change adding the struct keyword will allow us to keep the kernel-doc
descriptions more consistent for future changes, by checking for new kernel-doc
warnings.

Also, some of the files in ./include/ are not assigned to a specific
MAINTAINERS section and hence have no dedicated maintainer. So, if needed, the
files in ./include/ are also assigned to the fitting MAINTAINERS section, as I
need to identify whom to send the clean-up patch anyway.

Here is the change from this kernel-doc janitorial work in the ./include/
directory for ARM/QUALCOMM SUPPORT.

Andy, Bjorn, please pick this clean-up patch series for your tree.

Link: https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html


Lukas Bulwahn (2):
  MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT
  soc: qcom: address kernel-doc warnings

 MAINTAINERS                        | 1 +
 include/linux/soc/qcom/apr.h       | 2 +-
 include/linux/soc/qcom/irq.h       | 2 +-
 include/linux/soc/qcom/llcc-qcom.h | 6 +++---
 include/linux/soc/qcom/qmi.h       | 4 ++--
 5 files changed, 8 insertions(+), 7 deletions(-)

-- 
2.17.1