docs: kdoc_output: only use out_tail when the identfier is shown

[PATCH] docs: kdoc_output: only use out_tail when the identfier is shown

Posted by Randy Dunlap 1 month, 1 week ago

In -man mode, scripts/kernel-doc prints the "out_tail" information for
all symbols that are found (without the symbol info), whether the
symbols match the output selection criteria or not.

This can cause quite a lot of extraneous output in -man mode for the
symbols that are not in the selection criteria.

Modify kdoc_output.py so that it only calls out_tail() for symbols that
are being shown according to the selection criteria.

Closes: https://lore.kernel.org/all/fc7978bb-a71f-456d-84bb-670c8f0426ed@infradead.org/
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Shuah Khan <skhan@linuxfoundation.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-doc@vger.kernel.org

 tools/lib/python/kdoc/kdoc_output.py |    6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

--- linux-next-20260814.orig/tools/lib/python/kdoc/kdoc_output.py
+++ linux-next-20260814/tools/lib/python/kdoc/kdoc_output.py
@@ -198,22 +198,27 @@ class OutputFormat:
 
         if dtype == "function":
             self.out_function(fname, name, args)
+            self.out_tail(fname, name, args)
             return self.data
 
         if dtype == "enum":
             self.out_enum(fname, name, args)
+            self.out_tail(fname, name, args)
             return self.data
 
         if dtype == "var":
             self.out_var(fname, name, args)
+            self.out_tail(fname, name, args)
             return self.data
 
         if dtype == "typedef":
             self.out_typedef(fname, name, args)
+            self.out_tail(fname, name, args)
             return self.data
 
         if dtype in ["struct", "union"]:
             self.out_struct(fname, name, args)
+            self.out_tail(fname, name, args)
             return self.data
 
         # Warn if some type requires an output logic
@@ -763,7 +768,6 @@ class ManFormat(OutputFormat):
         Add a tail at the end of man pages output.
         """
         super().msg(fname, name, args)
-        self.out_tail(fname, name, args)
 
         return self.data

Re: [PATCH] docs: kdoc_output: only use out_tail when the identfier is shown

Posted by Randy Dunlap 1 month, 1 week ago

I think that I just found a problem with this.
I'll post an update when I have one.

On 8/15/26 10:48 PM, Randy Dunlap wrote:
> In -man mode, scripts/kernel-doc prints the "out_tail" information for
> all symbols that are found (without the symbol info), whether the
> symbols match the output selection criteria or not.
> 
> This can cause quite a lot of extraneous output in -man mode for the
> symbols that are not in the selection criteria.
> 
> Modify kdoc_output.py so that it only calls out_tail() for symbols that
> are being shown according to the selection criteria.
> 
> Closes: https://lore.kernel.org/all/fc7978bb-a71f-456d-84bb-670c8f0426ed@infradead.org/
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Shuah Khan <skhan@linuxfoundation.org>
> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
> Cc: linux-doc@vger.kernel.org
> 
>  tools/lib/python/kdoc/kdoc_output.py |    6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> --- linux-next-20260814.orig/tools/lib/python/kdoc/kdoc_output.py
> +++ linux-next-20260814/tools/lib/python/kdoc/kdoc_output.py
> @@ -198,22 +198,27 @@ class OutputFormat:
>  
>          if dtype == "function":
>              self.out_function(fname, name, args)
> +            self.out_tail(fname, name, args)
>              return self.data
>  
>          if dtype == "enum":
>              self.out_enum(fname, name, args)
> +            self.out_tail(fname, name, args)
>              return self.data
>  
>          if dtype == "var":
>              self.out_var(fname, name, args)
> +            self.out_tail(fname, name, args)
>              return self.data
>  
>          if dtype == "typedef":
>              self.out_typedef(fname, name, args)
> +            self.out_tail(fname, name, args)
>              return self.data
>  
>          if dtype in ["struct", "union"]:
>              self.out_struct(fname, name, args)
> +            self.out_tail(fname, name, args)
>              return self.data
>  
>          # Warn if some type requires an output logic
> @@ -763,7 +768,6 @@ class ManFormat(OutputFormat):
>          Add a tail at the end of man pages output.
>          """
>          super().msg(fname, name, args)
> -        self.out_tail(fname, name, args)
>  
>          return self.data
>  

-- 
~Randy

Re: [PATCH] docs: kdoc_output: only use out_tail when the identfier is shown

Posted by Randy Dunlap 1 month, 1 week ago

Hi Mauro et al,

On 8/16/26 11:05 AM, Randy Dunlap wrote:
> I think that I just found a problem with this.
> I'll post an update when I have one.
> 
> On 8/15/26 10:48 PM, Randy Dunlap wrote:
>> In -man mode, scripts/kernel-doc prints the "out_tail" information for
>> all symbols that are found (without the symbol info), whether the
>> symbols match the output selection criteria or not.
>>
>> This can cause quite a lot of extraneous output in -man mode for the
>> symbols that are not in the selection criteria.
>>
>> Modify kdoc_output.py so that it only calls out_tail() for symbols that
>> are being shown according to the selection criteria.
>>
>> Closes: https://lore.kernel.org/all/fc7978bb-a71f-456d-84bb-670c8f0426ed@infradead.org/
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>> Cc: Jonathan Corbet <corbet@lwn.net>
>> Cc: Shuah Khan <skhan@linuxfoundation.org>
>> Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
>> Cc: linux-doc@vger.kernel.org
>>
>>  tools/lib/python/kdoc/kdoc_output.py |    6 +++++-
>>  1 file changed, 5 insertions(+), 1 deletion(-)
>>

This change represents that I think would/could be a reasonable fix for
the problem that I reported (see the Closes: link).
However, this doesn't work because what I want to call (out_tail) does not
belong to the OutputFormat object but instead to the ManFormat class.

Can someone advise me on how I could/should call ManFormat.out_tail()
from here in the OutputFormat object?

  File "linux-next-20260814/tools/docs/../lib/python/kdoc/kdoc_output.py", line 221, in msg
    self.out_tail(fname, name, args)
    ^^^^^^^^^^^^^
AttributeError: 'OutputFormat' object has no attribute 'out_tail'. Did you mean: 'out_var'?


>> --- linux-next-20260814.orig/tools/lib/python/kdoc/kdoc_output.py
>> +++ linux-next-20260814/tools/lib/python/kdoc/kdoc_output.py
>> @@ -198,22 +198,27 @@ class OutputFormat:
>>  
>>          if dtype == "function":
>>              self.out_function(fname, name, args)
>> +            self.out_tail(fname, name, args)
>>              return self.data
>>  
>>          if dtype == "enum":
>>              self.out_enum(fname, name, args)
>> +            self.out_tail(fname, name, args)
>>              return self.data
>>  
>>          if dtype == "var":
>>              self.out_var(fname, name, args)
>> +            self.out_tail(fname, name, args)
>>              return self.data
>>  
>>          if dtype == "typedef":
>>              self.out_typedef(fname, name, args)
>> +            self.out_tail(fname, name, args)
>>              return self.data
>>  
>>          if dtype in ["struct", "union"]:
>>              self.out_struct(fname, name, args)
>> +            self.out_tail(fname, name, args)
>>              return self.data
>>  
>>          # Warn if some type requires an output logic
>> @@ -763,7 +768,6 @@ class ManFormat(OutputFormat):
>>          Add a tail at the end of man pages output.
>>          """
>>          super().msg(fname, name, args)
>> -        self.out_tail(fname, name, args)
>>  
>>          return self.data
>>  
> 

Thanks.
-- 
~Randy