Parsing a file like drivers/scsi/isci/host.h, which contains
broken kernel-doc markups makes it create a prototype that contains
unmatched end comments.

That causes, for instance, struct sci_power_control to be shown this
this prototype:

    struct sci_power_control {
        * it is not. */ bool timer_started;
        */ struct sci_timer timer;
        * requesters field. */ u8 phys_waiting;
        */ u8 phys_granted_power;
        * mapped into requesters via struct sci_phy.phy_index */ struct isci_phy *requesters[SCI_MAX_PHYS];
    };

as comments won't start with "/*" anymore.

Fix the logic to detect such cases, and keep adding the comments
inside it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <18e577dbbd538dcc22945ff139fe3638344e14f0.1773074166.git.mchehab+huawei@kernel.org>
---
 tools/lib/python/kdoc/kdoc_parser.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index edf70ba139a5..086579d00b5c 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -1355,6 +1355,12 @@ class KernelDoc:
         elif doc_content.search(line):
             self.emit_msg(ln, f"Incorrect use of kernel-doc format: {line}")
             self.state = state.PROTO
+
+            #
+            # Don't let it add partial comments at the code, as breaks the
+            # logic meant to remove comments from prototypes.
+            #
+            self.process_proto_type(ln, "/**\n" + line)
         # else ... ??
 
     def process_inline_text(self, ln, line):
-- 
2.52.0

> -----Original Message-----
> From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Sent: Tuesday, March 17, 2026 7:09 PM
> To: Jonathan Corbet <corbet@lwn.net>; Linux Doc Mailing List <linux-
> doc@vger.kernel.org>
> Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>; linux-
> hardening@vger.kernel.org; linux-kernel@vger.kernel.org; Loktionov,
> Aleksandr <aleksandr.loktionov@intel.com>; Randy Dunlap
> <rdunlap@infradead.org>
> Subject: [PATCH v3 03/22] docs: kdoc: don't add broken comments inside
> prototypes
> 
> Parsing a file like drivers/scsi/isci/host.h, which contains broken
> kernel-doc markups makes it create a prototype that contains unmatched
> end comments.
> 
> That causes, for instance, struct sci_power_control to be shown this
> this prototype:
> 
>     struct sci_power_control {
>         * it is not. */ bool timer_started;
>         */ struct sci_timer timer;
>         * requesters field. */ u8 phys_waiting;
>         */ u8 phys_granted_power;
>         * mapped into requesters via struct sci_phy.phy_index */
> struct isci_phy *requesters[SCI_MAX_PHYS];
>     };
> 
> as comments won't start with "/*" anymore.
> 
> Fix the logic to detect such cases, and keep adding the comments
> inside it.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> Message-ID:
> <18e577dbbd538dcc22945ff139fe3638344e14f0.1773074166.git.mchehab+huawe
> i@kernel.org>
> ---
>  tools/lib/python/kdoc/kdoc_parser.py | 6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_parser.py
> b/tools/lib/python/kdoc/kdoc_parser.py
> index edf70ba139a5..086579d00b5c 100644
> --- a/tools/lib/python/kdoc/kdoc_parser.py
> +++ b/tools/lib/python/kdoc/kdoc_parser.py
> @@ -1355,6 +1355,12 @@ class KernelDoc:
>          elif doc_content.search(line):
>              self.emit_msg(ln, f"Incorrect use of kernel-doc format:
> {line}")
>              self.state = state.PROTO
> +
> +            #
> +            # Don't let it add partial comments at the code, as
> breaks the
> +            # logic meant to remove comments from prototypes.
> +            #
> +            self.process_proto_type(ln, "/**\n" + line)
>          # else ... ??
> 
>      def process_inline_text(self, ln, line):
> --
> 2.52.0

Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com>