[PATCH] scripts: kernel-doc: add warning for comment not following kernel-doc syntax

[Lee Jones]

On Mon, 29 Mar 2021 at 10:30, Aditya Srivastava <yashsri421 at gmail.com>
wrote:

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

Actually this patch makes things worse by obfuscating the issue.  It was
way better before.

In the example you give, it's obvious to me that there is descriptive text
where the prototype should be.

Now I just get a warning that this "isn't a kernel-doc comment", which a)
is not correct and b) could mean anything.

Please consider reverting this patch, as it does the opposite of its intent.

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 at gmail.com>
> ---
>  scripts/kernel-doc | 17 +++++++++++++----
>  1 file changed, 13 insertions(+), 4 deletions(-)
>
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index cb92d0e1e932..b1d71a7b721f 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -2103,15 +2103,17 @@ sub process_name($$) {
>         }
>      } elsif (/$doc_decl/o) {
>         $identifier = $1;
> -       if (/\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
> +       my $is_kernel_comment = 0;
> +       if (/^\s*\*\s*([\w\s]+?)(\(\))?\s*([-:].*)?$/) {
>             $identifier = $1;
> +           $decl_type = 'function';
> +           $identifier =~ s/^define\s+//;
> +           $is_kernel_comment = 1;
>         }
>         if ($identifier =~ m/^(struct|union|enum|typedef)\b\s*(\S*)/) {
>             $decl_type = $1;
>             $identifier = $2;
> -       } else {
> -           $decl_type = 'function';
> -           $identifier =~ s/^define\s+//;
> +           $is_kernel_comment = 1;
>         }
>         $identifier =~ s/\s+$//;
>
> @@ -2133,6 +2135,13 @@ sub process_name($$) {
>             $declaration_purpose = "";
>         }
>
> +       if (!$is_kernel_comment) {
> +           print STDERR "${file}:$.: warning: This comment starts with
> '/**', but isn't a kernel-doc comment. Refer
> Documentation/doc-guide/kernel-doc.rst\n";
> +           print STDERR $_;
> +           ++$warnings;
> +           $state = STATE_NORMAL;
> +       }
> +
>         if (($declaration_purpose eq "") && $verbose) {
>             print STDERR "${file}:$.: warning: missing initial short
> description on line:\n";
>             print STDERR $_;
> --
> 2.17.1
>

-- 
Lee Jones [李琼斯]
Linaro Services Senior Technical Lead
Linaro.org │ Open source software for ARM SoCs
Follow Linaro: Facebook | Twitter | Blog
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20210524/cbcf967a/attachment.html>