On 29/3/21 7:26 pm, Jonathan Corbet wrote: > Aditya Srivastava <yashsri421@xxxxxxxxx> writes: > >> Currently, kernel-doc start parsing the comment as a kernel-doc comment if >> it starts with '/**', but does not take into account if the content inside >> the comment too, adheres with the expected format. >> This results in unexpected and unclear warnings for the user. >> >> E.g., running scripts/kernel-doc -none mm/memcontrol.c emits: >> "mm/memcontrol.c:961: warning: expecting prototype for do not fallback to current(). Prototype was for get_mem_cgroup_from_current() instead" >> >> Here kernel-doc parses the corresponding comment as a kernel-doc comment >> and expects prototype for it in the next lines, and as a result causing >> this warning. >> >> Provide a clearer warning message to the users regarding the same, if the >> content inside the comment does not follow the kernel-doc expected format. >> >> Signed-off-by: Aditya Srivastava <yashsri421@xxxxxxxxx> >> --- >> scripts/kernel-doc | 17 +++++++++++++---- >> 1 file changed, 13 insertions(+), 4 deletions(-) > > This is definitely a capability we want, but I really don't think that > we can turn it on by default - for now. Experience shows that if you > create a blizzard of warnings, nobody sees any of them. How many > warnings does this add to a full docs build? > Hi Jonathan, here's the diff I have created for the warnings before and after the changes: https://github.com/AdityaSrivast/kernel-tasks/blob/master/random/kernel-doc/kernel_doc_comment_syntax.txt Around ~1320 new warnings of this type are added to the kernel tree, and around ~1580 warnings are removed. Thanks Aditya > For now I think we need a flag to turn this warning on, which perhaps > can be set for a W=1 build. > > Thanks, > > jon >
