On 29/3/21 7:26 pm, Jonathan Corbet wrote:

Aditya Srivastava [off-list ref] writes:

quoted

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 <redacted>
---
 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.

quoted

Thanks,

jon

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees