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
