[PATCH] kernel-doc: Fix symbol matching for dropped suffixes

[PATCH] kernel-doc: Fix symbol matching for dropped suffixes

[Matthew Wilcox (Oracle)]

The support for dropping "_noprof" missed dropping the suffix from
exported symbols.  That meant that using the :export: feature would
look for kernel-doc for (eg) krealloc_noprof() and not find the
kernel-doc for krealloc().

Fixes: 51a7bf0238c2 (scripts/kernel-doc: drop "_noprof" on function prototypes)
Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 scripts/lib/kdoc/kdoc_parser.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
index 062453eefc7a..2c6143f7ca0f 100644
--- a/scripts/lib/kdoc/kdoc_parser.py
+++ b/scripts/lib/kdoc/kdoc_parser.py
@@ -1171,16 +1171,24 @@ class KernelDoc:
         with a staticmethod decorator.
         """
 
+        # We support documenting some exported symbols with different
+        # names.  A horrible hack.
+        suffixes = [ '_noprof' ]
+
         # Note: it accepts only one EXPORT_SYMBOL* per line, as having
         # multiple export lines would violate Kernel coding style.
 
         if export_symbol.search(line):
             symbol = export_symbol.group(2)
+            for suffix in suffixes:
+                symbol = symbol.removesuffix(suffix)
             function_set.add(symbol)
             return
 
         if export_symbol_ns.search(line):
             symbol = export_symbol_ns.group(2)
+            for suffix in suffixes:
+                symbol = symbol.removesuffix(suffix)
             function_set.add(symbol)
 
     def process_normal(self, ln, line):
-- 
2.47.2

Re: [PATCH] kernel-doc: Fix symbol matching for dropped suffixes

[Mauro Carvalho Chehab]

Em Fri,  6 Jun 2025 15:15:42 +0100
"Matthew Wilcox (Oracle)" <willy@infradead.org> escreveu:

> The support for dropping "_noprof" missed dropping the suffix from
> exported symbols.  That meant that using the :export: feature would
> look for kernel-doc for (eg) krealloc_noprof() and not find the
> kernel-doc for krealloc().
> 
> Fixes: 51a7bf0238c2 (scripts/kernel-doc: drop "_noprof" on function prototypes)
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/scripts/lib/kdoc/kdoc_parser.py b/scripts/lib/kdoc/kdoc_parser.py
> index 062453eefc7a..2c6143f7ca0f 100644
> --- a/scripts/lib/kdoc/kdoc_parser.py
> +++ b/scripts/lib/kdoc/kdoc_parser.py
> @@ -1171,16 +1171,24 @@ class KernelDoc:
>          with a staticmethod decorator.
>          """
>  
> +        # We support documenting some exported symbols with different
> +        # names.  A horrible hack.
> +        suffixes = [ '_noprof' ]
> +
>          # Note: it accepts only one EXPORT_SYMBOL* per line, as having
>          # multiple export lines would violate Kernel coding style.
>  
>          if export_symbol.search(line):
>              symbol = export_symbol.group(2)
> +            for suffix in suffixes:
> +                symbol = symbol.removesuffix(suffix)
>              function_set.add(symbol)
>              return
>  
>          if export_symbol_ns.search(line):
>              symbol = export_symbol_ns.group(2)
> +            for suffix in suffixes:
> +                symbol = symbol.removesuffix(suffix)
>              function_set.add(symbol)

For now, this sounds ok to me.

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

>  
>      def process_normal(self, ln, line):



Thanks,
Mauro

Re: [PATCH] kernel-doc: Fix symbol matching for dropped suffixes

[Jonathan Corbet]

"Matthew Wilcox (Oracle)" <willy@infradead.org> writes:

> The support for dropping "_noprof" missed dropping the suffix from
> exported symbols.  That meant that using the :export: feature would
> look for kernel-doc for (eg) krealloc_noprof() and not find the
> kernel-doc for krealloc().
>
> Fixes: 51a7bf0238c2 (scripts/kernel-doc: drop "_noprof" on function prototypes)
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  scripts/lib/kdoc/kdoc_parser.py | 8 ++++++++
>  1 file changed, 8 insertions(+)

I've applied this.  Naturally, it gifts us with a new docs build
warning:

> Documentation/core-api/mm-api:40: ./mm/slub.c:4936: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
> Documentation/core-api/mm-api:40: ./mm/slub.c:4936: ERROR: Undefined substitution referenced: "--------". [docutils]

I was hoping your other slab patch series address this, but it doesn't
look that way...?

Thanks,

jon

Re: [PATCH] kernel-doc: Fix symbol matching for dropped suffixes

[Matthew Wilcox]

On Mon, Jun 09, 2025 at 02:23:56PM -0600, Jonathan Corbet wrote:
> "Matthew Wilcox (Oracle)" <willy@infradead.org> writes:
> 
> > The support for dropping "_noprof" missed dropping the suffix from
> > exported symbols.  That meant that using the :export: feature would
> > look for kernel-doc for (eg) krealloc_noprof() and not find the
> > kernel-doc for krealloc().
> >
> > Fixes: 51a7bf0238c2 (scripts/kernel-doc: drop "_noprof" on function prototypes)
> > Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> > ---
> >  scripts/lib/kdoc/kdoc_parser.py | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> 
> I've applied this.  Naturally, it gifts us with a new docs build
> warning:
> 
> > Documentation/core-api/mm-api:40: ./mm/slub.c:4936: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
> > Documentation/core-api/mm-api:40: ./mm/slub.c:4936: ERROR: Undefined substitution referenced: "--------". [docutils]
> 
> I was hoping your other slab patch series address this, but it doesn't
> look that way...?

Indeed it does.

It's a pre-existing bug, that's only unmaked by this patch.  Honestly,
I'm not that great at kerneldoc and I was hoping someone like Randy
would notice and fix it ;-)

Re: [PATCH] kernel-doc: Fix symbol matching for dropped suffixes

[Jonathan Corbet]

Matthew Wilcox <willy@infradead.org> writes:

>> I've applied this.  Naturally, it gifts us with a new docs build
>> warning:
>> 
>> > Documentation/core-api/mm-api:40: ./mm/slub.c:4936: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
>> > Documentation/core-api/mm-api:40: ./mm/slub.c:4936: ERROR: Undefined substitution referenced: "--------". [docutils]
>> 
>> I was hoping your other slab patch series address this, but it doesn't
>> look that way...?
>
> Indeed it does.
>
> It's a pre-existing bug, that's only unmaked by this patch.

I knew that, that's why I hoped the other series maybe addressed it. 

> Honestly,
> I'm not that great at kerneldoc and I was hoping someone like Randy
> would notice and fix it ;-)

The attached fixes it, but may conflict with your other work.

jon

From 6b3b23e49b57a377716870bc752b884f324ad342 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Mon, 9 Jun 2025 15:05:46 -0600
Subject: [PATCH] mm: slub: Fix a documentation build error for kerealloc()

The kerneldoc comment for krealloc() contains an unmarked literal block,
leading to these warnings in the docs build:

  Documentation/core-api/mm-api:40: ./mm/slub.c:4936: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
  Documentation/core-api/mm-api:40: ./mm/slub.c:4936: ERROR: Undefined substitution referenced: "--------". [docutils]

Mark up and indent the block properly to bring a bit of peace to our build
logs.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>
---
 mm/slub.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/mm/slub.c b/mm/slub.c
index 31e11ef256f9..45a963e363d3 100644
--- a/mm/slub.c
+++ b/mm/slub.c
@@ -4930,12 +4930,12 @@ __do_krealloc(const void *p, size_t new_size, gfp_t flags)
  * When slub_debug_orig_size() is off, krealloc() only knows about the bucket
  * size of an allocation (but not the exact size it was allocated with) and
  * hence implements the following semantics for shrinking and growing buffers
- * with __GFP_ZERO.
+ * with __GFP_ZERO::
  *
- *         new             bucket
- * 0       size             size
- * |--------|----------------|
- * |  keep  |      zero      |
+ *           new             bucket
+ *   0       size             size
+ *   |--------|----------------|
+ *   |  keep  |      zero      |
  *
  * Otherwise, the original allocation size 'orig_size' could be used to
  * precisely clear the requested size, and the new size will also be stored
-- 
2.49.0