mbox series

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

Message ID 20210327065642.11969-1-lukas.bulwahn@gmail.com
Headers show
Series kernel-doc and MAINTAINERS clean-up | expand

Message

Lukas Bulwahn March 27, 2021, 6:56 a.m. UTC 
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(-)

Comments

patchwork-bot+linux-arm-msm@kernel.org April 4, 2021, 6:10 p.m. UTC | #1 
Hello:

This series was applied to qcom/linux.git (refs/heads/for-next):

On Sat, 27 Mar 2021 07:56:40 +0100 you wrote:
> 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.

> 

> [...]


Here is the summary with links:
  - [1/2] MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT
    https://git.kernel.org/qcom/c/99d52c872d34
  - [2/2] soc: qcom: address kernel-doc warnings
    https://git.kernel.org/qcom/c/8058dfa05ab7

You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html