entry::is_kernel_comment never had anything to do with the entry itself; it
is a bit of local state in one branch of process_name().  It can, in fact,
be removed entirely; rework the code slightly so that it is no longer
needed.

No change in the rendered output.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 scripts/lib/kdoc/kdoc_parser.py | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 3ea260b423e2..56299695abd1 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1216,7 +1216,6 @@ class KernelDoc:
 
         if doc_decl.search(line):
             self.entry.identifier = doc_decl.group(1)
-            self.entry.is_kernel_comment = False
 
             decl_start = str(doc_com)       # comment block asterisk
             fn_type = r"(?:\w+\s*\*\s*)?"  # type (for non-functions)
@@ -1234,14 +1233,20 @@ class KernelDoc:
             if r.search(line):
                 self.entry.decl_type = r.group(1)
                 self.entry.identifier = r.group(2)
-                self.entry.is_kernel_comment = True
             #
             # Look for a function description
             #
             elif r2.search(line):
                 self.entry.identifier = r2.group(1)
                 self.entry.decl_type = "function"
-                self.entry.is_kernel_comment = True
+            #
+            # We struck out.
+            #
+            else:
+                self.emit_msg(ln,
+                              f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
+                self.state = state.NORMAL
+                return
 
             self.entry.identifier = self.entry.identifier.strip(" ")
 
@@ -1263,11 +1268,6 @@ class KernelDoc:
             else:
                 self.entry.declaration_purpose = ""
 
-            if not self.entry.is_kernel_comment:
-                self.emit_msg(ln,
-                              f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
-                self.state = state.NORMAL
-
             if not self.entry.declaration_purpose and self.config.wshort_desc:
                 self.emit_msg(ln,
                               f"missing initial short description on line:\n{line}")
-- 
2.49.0

Em Fri,  6 Jun 2025 10:34:34 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> entry::is_kernel_comment never had anything to do with the entry itself; it
> is a bit of local state in one branch of process_name().  It can, in fact,
> be removed entirely; rework the code slightly so that it is no longer
> needed.
> 
> No change in the rendered output.
> 
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Not sure about this one. The idea of those warnings are to detect 
non-kerneldoc markups that typically comes when someone "imports"
OOT drivers or Windows one into Linux.

I remember I catched several such cases in the past with the help
of those warnings.

> ---
>  scripts/lib/kdoc/kdoc_parser.py | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 3ea260b423e2..56299695abd1 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1216,7 +1216,6 @@ class KernelDoc:
>  
>          if doc_decl.search(line):
>              self.entry.identifier = doc_decl.group(1)
> -            self.entry.is_kernel_comment = False
>  
>              decl_start = str(doc_com)       # comment block asterisk
>              fn_type = r"(?:\w+\s*\*\s*)?"  # type (for non-functions)
> @@ -1234,14 +1233,20 @@ class KernelDoc:
>              if r.search(line):
>                  self.entry.decl_type = r.group(1)
>                  self.entry.identifier = r.group(2)
> -                self.entry.is_kernel_comment = True
>              #
>              # Look for a function description
>              #
>              elif r2.search(line):
>                  self.entry.identifier = r2.group(1)
>                  self.entry.decl_type = "function"
> -                self.entry.is_kernel_comment = True
> +            #
> +            # We struck out.
> +            #
> +            else:
> +                self.emit_msg(ln,
> +                              f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
> +                self.state = state.NORMAL
> +                return
>  
>              self.entry.identifier = self.entry.identifier.strip(" ")
>  
> @@ -1263,11 +1268,6 @@ class KernelDoc:
>              else:
>                  self.entry.declaration_purpose = ""
>  
> -            if not self.entry.is_kernel_comment:
> -                self.emit_msg(ln,
> -                              f"This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst\n{line}")
> -                self.state = state.NORMAL
> -
>              if not self.entry.declaration_purpose and self.config.wshort_desc:
>                  self.emit_msg(ln,
>                                f"missing initial short description on line:\n{line}")



Thanks,
Mauro

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Em Fri,  6 Jun 2025 10:34:34 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> entry::is_kernel_comment never had anything to do with the entry itself; it
>> is a bit of local state in one branch of process_name().  It can, in fact,
>> be removed entirely; rework the code slightly so that it is no longer
>> needed.
>> 
>> No change in the rendered output.
>> 
>> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
>
> Not sure about this one. The idea of those warnings are to detect 
> non-kerneldoc markups that typically comes when someone "imports"
> OOT drivers or Windows one into Linux.
>
> I remember I catched several such cases in the past with the help
> of those warnings.

I haven't removed the warning, just the use of that specific variable to
trigger it.

Thanks,

jon

Em Sat, 07 Jun 2025 07:22:51 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Em Fri,  6 Jun 2025 10:34:34 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >  
> >> entry::is_kernel_comment never had anything to do with the entry itself; it
> >> is a bit of local state in one branch of process_name().  It can, in fact,
> >> be removed entirely; rework the code slightly so that it is no longer
> >> needed.
> >> 
> >> No change in the rendered output.
> >> 
> >> Signed-off-by: Jonathan Corbet <corbet@lwn.net>  
> >
> > Not sure about this one. The idea of those warnings are to detect 
> > non-kerneldoc markups that typically comes when someone "imports"
> > OOT drivers or Windows one into Linux.
> >
> > I remember I catched several such cases in the past with the help
> > of those warnings.  
> 
> I haven't removed the warning, just the use of that specific variable to
> trigger it.

After looking a the patch again, it sounds OK to me.

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Regards,
Mauro