* [PATCH 0/2] kernel-doc and MAINTAINERS clean-up
@ 2021-03-27 6:56 Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 1/2] MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT Lukas Bulwahn
` (2 more replies)
0 siblings, 3 replies; 4+ messages in thread
From: Lukas Bulwahn @ 2021-03-27 6:56 UTC (permalink / raw)
To: Andy Gross, Bjorn Andersson
Cc: linux-arm-msm, Ralf Ramsauer, linux-doc, kernel-janitors,
linux-kernel, 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
^ permalink raw reply [flat|nested] 4+ messages in thread
* [PATCH 1/2] MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT
2021-03-27 6:56 [PATCH 0/2] kernel-doc and MAINTAINERS clean-up Lukas Bulwahn
@ 2021-03-27 6:56 ` Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 2/2] soc: qcom: address kernel-doc warnings Lukas Bulwahn
2021-04-04 18:10 ` [PATCH 0/2] kernel-doc and MAINTAINERS clean-up patchwork-bot+linux-arm-msm
2 siblings, 0 replies; 4+ messages in thread
From: Lukas Bulwahn @ 2021-03-27 6:56 UTC (permalink / raw)
To: Andy Gross, Bjorn Andersson
Cc: linux-arm-msm, Ralf Ramsauer, linux-doc, kernel-janitors,
linux-kernel, Lukas Bulwahn
The files in ./include/linux/soc/qcom/ are headers to the corresponding
files in ./drivers/soc/qcom/, which are assigned to ARM/QUALCOMM SUPPORT.
Possibly, the file pattern include/linux/*/qcom* intended to match this
directory and its containing files, but unfortunately, it does not.
Hence, add a file entry for this directory to ARM/QUALCOMM SUPPORT.
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 67b104202602..ec43d5c3a1a4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2298,6 +2298,7 @@ F: drivers/tty/serial/msm_serial.c
F: drivers/usb/dwc3/dwc3-qcom.c
F: include/dt-bindings/*/qcom*
F: include/linux/*/qcom*
+F: include/linux/soc/qcom/
ARM/RADISYS ENP2611 MACHINE SUPPORT
M: Lennert Buytenhek <kernel@wantstofly.org>
--
2.17.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* [PATCH 2/2] soc: qcom: address kernel-doc warnings
2021-03-27 6:56 [PATCH 0/2] kernel-doc and MAINTAINERS clean-up Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 1/2] MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT Lukas Bulwahn
@ 2021-03-27 6:56 ` Lukas Bulwahn
2021-04-04 18:10 ` [PATCH 0/2] kernel-doc and MAINTAINERS clean-up patchwork-bot+linux-arm-msm
2 siblings, 0 replies; 4+ messages in thread
From: Lukas Bulwahn @ 2021-03-27 6:56 UTC (permalink / raw)
To: Andy Gross, Bjorn Andersson
Cc: linux-arm-msm, Ralf Ramsauer, linux-doc, kernel-janitors,
linux-kernel, Lukas Bulwahn
The command:
find ./include/linux/soc/qcom/ | xargs ./scripts/kernel-doc -none
reports:
./include/linux/soc/qcom/qmi.h:26: warning: cannot understand function prototype: 'struct qmi_header '
./include/linux/soc/qcom/qmi.h:101: warning: cannot understand function prototype: 'struct qmi_response_type_v01 '
./include/linux/soc/qcom/irq.h:19: warning: expecting prototype for QCOM specific IRQ domain flags that distinguishes the handling of wakeup(). Prototype was for IRQ_DOMAIN_FLAG_QCOM_PDC_WAKEUP() instead
./include/linux/soc/qcom/apr.h:126: warning: Function parameter or member '__apr_driver' not described in 'module_apr_driver'
./include/linux/soc/qcom/apr.h:126: warning: Excess function parameter '__aprbus_driver' description in 'module_apr_driver'
./include/linux/soc/qcom/llcc-qcom.h:43: warning: cannot understand function prototype: 'struct llcc_slice_desc '
./include/linux/soc/qcom/llcc-qcom.h:60: warning: cannot understand function prototype: 'struct llcc_edac_reg_data '
./include/linux/soc/qcom/llcc-qcom.h:86: warning: cannot understand function prototype: 'struct llcc_drv_data '
Address all those warnings by:
- prefixing kernel-doc descriptions for structs with the keyword 'struct',
- turning a kernel-doc comment that does not follow the kernel-doc syntax
into a normal comment, and
- correcting a parameter name in a kernel-doc comment.
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
---
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 ++--
4 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/include/linux/soc/qcom/apr.h b/include/linux/soc/qcom/apr.h
index 7f0bc3cf4d61..137f9f2ac4c3 100644
--- a/include/linux/soc/qcom/apr.h
+++ b/include/linux/soc/qcom/apr.h
@@ -113,7 +113,7 @@ void apr_driver_unregister(struct apr_driver *drv);
/**
* module_apr_driver() - Helper macro for registering a aprbus driver
- * @__aprbus_driver: aprbus_driver struct
+ * @__apr_driver: apr_driver struct
*
* Helper macro for aprbus drivers which do not do anything special in
* module init/exit. This eliminates a lot of boilerplate. Each module
diff --git a/include/linux/soc/qcom/irq.h b/include/linux/soc/qcom/irq.h
index 9e1ece58e55b..72b9231e9fdd 100644
--- a/include/linux/soc/qcom/irq.h
+++ b/include/linux/soc/qcom/irq.h
@@ -7,7 +7,7 @@
#define GPIO_NO_WAKE_IRQ ~0U
-/**
+/*
* QCOM specific IRQ domain flags that distinguishes the handling of wakeup
* capable interrupts by different interrupt controllers.
*
diff --git a/include/linux/soc/qcom/llcc-qcom.h b/include/linux/soc/qcom/llcc-qcom.h
index 64fc582ae415..437c9df13229 100644
--- a/include/linux/soc/qcom/llcc-qcom.h
+++ b/include/linux/soc/qcom/llcc-qcom.h
@@ -35,7 +35,7 @@
#define LLCC_WRCACHE 31
/**
- * llcc_slice_desc - Cache slice descriptor
+ * struct llcc_slice_desc - Cache slice descriptor
* @slice_id: llcc slice id
* @slice_size: Size allocated for the llcc slice
*/
@@ -45,7 +45,7 @@ struct llcc_slice_desc {
};
/**
- * llcc_edac_reg_data - llcc edac registers data for each error type
+ * struct llcc_edac_reg_data - llcc edac registers data for each error type
* @name: Name of the error
* @synd_reg: Syndrome register address
* @count_status_reg: Status register address to read the error count
@@ -69,7 +69,7 @@ struct llcc_edac_reg_data {
};
/**
- * llcc_drv_data - Data associated with the llcc driver
+ * struct llcc_drv_data - Data associated with the llcc driver
* @regmap: regmap associated with the llcc device
* @bcast_regmap: regmap associated with llcc broadcast offset
* @cfg: pointer to the data structure for slice configuration
diff --git a/include/linux/soc/qcom/qmi.h b/include/linux/soc/qcom/qmi.h
index e712f94b89fc..b1f80e756d2a 100644
--- a/include/linux/soc/qcom/qmi.h
+++ b/include/linux/soc/qcom/qmi.h
@@ -16,7 +16,7 @@
struct socket;
/**
- * qmi_header - wireformat header of QMI messages
+ * struct qmi_header - wireformat header of QMI messages
* @type: type of message
* @txn_id: transaction id
* @msg_id: message id
@@ -93,7 +93,7 @@ struct qmi_elem_info {
#define QMI_ERR_NOT_SUPPORTED_V01 94
/**
- * qmi_response_type_v01 - common response header (decoded)
+ * struct qmi_response_type_v01 - common response header (decoded)
* @result: result of the transaction
* @error: error value, when @result is QMI_RESULT_FAILURE_V01
*/
--
2.17.1
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH 0/2] kernel-doc and MAINTAINERS clean-up
2021-03-27 6:56 [PATCH 0/2] kernel-doc and MAINTAINERS clean-up Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 1/2] MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 2/2] soc: qcom: address kernel-doc warnings Lukas Bulwahn
@ 2021-04-04 18:10 ` patchwork-bot+linux-arm-msm
2 siblings, 0 replies; 4+ messages in thread
From: patchwork-bot+linux-arm-msm @ 2021-04-04 18:10 UTC (permalink / raw)
To: Lukas Bulwahn; +Cc: linux-arm-msm
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
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2021-04-04 18:10 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-03-27 6:56 [PATCH 0/2] kernel-doc and MAINTAINERS clean-up Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 1/2] MAINTAINERS: add another entry for ARM/QUALCOMM SUPPORT Lukas Bulwahn
2021-03-27 6:56 ` [PATCH 2/2] soc: qcom: address kernel-doc warnings Lukas Bulwahn
2021-04-04 18:10 ` [PATCH 0/2] kernel-doc and MAINTAINERS clean-up patchwork-bot+linux-arm-msm
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).