about make mandocs warnings

about make mandocs warnings

[Randy Dunlap]

Hi Mauro,


'make mandocs' on the full kernel tree generates a little over 10,000
lines of Warning:s.  Then it says:
  Warning: kernel-doc returned 138 warnings

What does that number mean?

kernel-doc is doing a very good job at finding issues in kernel-doc
notation, but there are a few cases of erroneous reporting. These are not
numerous and may not be worth much effort to fix them, although
some of them should not take much effort (I think). But I am just
reporting these in case someone wants to fix them.


Examples:

Warning: drivers/misc/vmw_balloon.c:259 struct member '5' not described in 'vmballoon_batch_entry'
"5" is part of an expression "PAGE_SHIFT - 5" for number of bits in a bitfield:
struct vmballoon_batch_entry {
	u64 status : 5;
	u64 reserved : PAGE_SHIFT - 5;
	u64 pfn : 52;
} __packed;

Warning: net/netfilter/nft_set_pipapo.h:102 union member '32' not described in 'nft_pipapo_map_bucket'
"32" is part of a static_assert() expression. Probably just
ignore the entire static_assert() [any number of lines].


Warning: include/linux/hrtimer_types.h:47 Invalid param: enum hrtimer_restart            (*__private function)(struct hrtimer *)
Warning: include/linux/hrtimer_types.h:47 struct member 'enum hrtimer_restart            (*__private function' not described in 'hrtimer'
"__private" is an attribute from <linux/compiler_types.h> and the
struct member here should be "function", which is described.


Warning: include/linux/rethook.h:38 Invalid param: void (__rcu *handler) (struct rethook_node *, void *, unsigned long, struct pt_regs *)
Warning: include/linux/rethook.h:38 struct member 'void (__rcu *handler' not described in 'rethook'
"__rcu" is an attribute from <linux/compiler_types.h> and the
struct member here is "handler", which is described.

Warning: security/ipe/hooks.c:54 function parameter '__always_unused' not described in 'ipe_mmap_file'
Warning: security/ipe/hooks.c:82 function parameter '__always_unused' not described in 'ipe_file_mprotect'
"__always_unused" is an attribute from <linux/compiler_attributes.h>.



Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent1)[LANDLOCK_NUM_ACCESS_FS]
Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent1' not described in 'is_access_to_paths_allowed'
Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent2)[LANDLOCK_NUM_ACCESS_FS]
Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent2' not described in 'is_access_to_paths_allowed'
@layer_masks_parent1 and @layer_masks_parent2 are described in kernel-doc.

Warning: security/landlock/fs.c:1142 Invalid param: layer_mask_t (*const layer_masks_dom)[LANDLOCK_NUM_ACCESS_FS]
Warning: security/landlock/fs.c:1142 function parameter 'layer_mask_t (*const layer_masks_dom' not described in 'collect_domain_accesses'
@layer_masks_dom is described in kernel-doc.

Warning: security/landlock/ruleset.c:210 Invalid param: const struct landlock_layer (*const layers)[]
Warning: security/landlock/ruleset.c:210 function parameter 'const struct landlock_layer (*const layers' not described in 'insert_rule'
@layers is described in kernel-doc.

Warning: security/landlock/ruleset.c:693 Invalid param: layer_mask_t (*const layer_masks)[]
Warning: security/landlock/ruleset.c:693 function parameter 'layer_mask_t (*const layer_masks' not described in 'landlock_init_layer_masks'
@layer_masks is described in kernel-doc.



Note: hundreds (probably thousands) of the mandocs warnings would disappear
if kernel-doc accepted '-' in addition to ':' as a function parameter
or struct/union/enum member separator (like it does for
function/struct/union/enum short description).

-- 
~Randy

Re: about make mandocs warnings

[Mauro Carvalho Chehab]

Em Sat, 25 Oct 2025 16:49:21 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi Mauro,
> 
> 
> 'make mandocs' on the full kernel tree generates a little over 10,000
> lines of Warning:s.  Then it says:
>   Warning: kernel-doc returned 138 warnings
> 
> What does that number mean?

Basically, at kdoc_files, we have:

    def warning(self, msg):
        """Ancillary routine to output a warning and increment error count"""

        self.config.log.warning(msg)
        self.errors += 1

    def error(self, msg):
        """Ancillary routine to output an error and increment error count"""

        self.config.log.error(msg)
        self.errors += 1

And kernel-doc itself exits with:

	error_count = kfiles.errors
	sys.exit(error_count)

I guess the problem here is that POSIX exit codes are 8 bits only, so
it ends reporting a wrong number of errors. Not sure what would be the
best way to fix it.

> kernel-doc is doing a very good job at finding issues in kernel-doc
> notation, but there are a few cases of erroneous reporting. These are not
> numerous and may not be worth much effort to fix them, although
> some of them should not take much effort (I think). But I am just
> reporting these in case someone wants to fix them.
> 
> 
> Examples:
> 
> Warning: drivers/misc/vmw_balloon.c:259 struct member '5' not described in 'vmballoon_batch_entry'
> "5" is part of an expression "PAGE_SHIFT - 5" for number of bits in a bitfield:
> struct vmballoon_batch_entry {
> 	u64 status : 5;
> 	u64 reserved : PAGE_SHIFT - 5;
> 	u64 pfn : 52;
> } __packed;

Fixing this one could be tricky, if we want to allow math expressions 
at the regex, but sounds doable.

> 
> Warning: net/netfilter/nft_set_pipapo.h:102 union member '32' not described in 'nft_pipapo_map_bucket'
> "32" is part of a static_assert() expression. Probably just
> ignore the entire static_assert() [any number of lines].

Yeah.

> Warning: include/linux/hrtimer_types.h:47 Invalid param: enum hrtimer_restart            (*__private function)(struct hrtimer *)
> Warning: include/linux/hrtimer_types.h:47 struct member 'enum hrtimer_restart            (*__private function' not described in 'hrtimer'
> "__private" is an attribute from <linux/compiler_types.h> and the
> struct member here should be "function", which is described.
> 
> 
> Warning: include/linux/rethook.h:38 Invalid param: void (__rcu *handler) (struct rethook_node *, void *, unsigned long, struct pt_regs *)
> Warning: include/linux/rethook.h:38 struct member 'void (__rcu *handler' not described in 'rethook'
> "__rcu" is an attribute from <linux/compiler_types.h> and the
> struct member here is "handler", which is described.
> 
> Warning: security/ipe/hooks.c:54 function parameter '__always_unused' not described in 'ipe_mmap_file'
> Warning: security/ipe/hooks.c:82 function parameter '__always_unused' not described in 'ipe_file_mprotect'
> "__always_unused" is an attribute from <linux/compiler_attributes.h>.
> 

Probably all we need for the above is to add one line for each,
to ignore the above macros.

> 
> Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent1)[LANDLOCK_NUM_ACCESS_FS]
> Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent1' not described in 'is_access_to_paths_allowed'
> Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent2)[LANDLOCK_NUM_ACCESS_FS]
> Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent2' not described in 'is_access_to_paths_allowed'
> @layer_masks_parent1 and @layer_masks_parent2 are described in kernel-doc.
>
> Warning: security/landlock/fs.c:1142 Invalid param: layer_mask_t (*const layer_masks_dom)[LANDLOCK_NUM_ACCESS_FS]
> Warning: security/landlock/fs.c:1142 function parameter 'layer_mask_t (*const layer_masks_dom' not described in 'collect_domain_accesses'
> @layer_masks_dom is described in kernel-doc.
>
> 
> Warning: security/landlock/ruleset.c:210 Invalid param: const struct landlock_layer (*const layers)[]
> Warning: security/landlock/ruleset.c:210 function parameter 'const struct landlock_layer (*const layers' not described in 'insert_rule'
> @layers is described in kernel-doc.
> 
> Warning: security/landlock/ruleset.c:693 Invalid param: layer_mask_t (*const layer_masks)[]
> Warning: security/landlock/ruleset.c:693 function parameter 'layer_mask_t (*const layer_masks' not described in 'landlock_init_layer_masks'
> @layer_masks is described in kernel-doc.

These would require some extra logic - or a fix at an existing one - to 
better handle parenthesis on arguments.

> Note: hundreds (probably thousands) of the mandocs warnings would disappear
> if kernel-doc accepted '-' in addition to ':' as a function parameter
> or struct/union/enum member separator (like it does for
> function/struct/union/enum short description).

This is easy to fix, and QEMU has a patch mentioning what is needed
at:
	9cbe72b868b7 ("scripts/kernel-doc: tweak for QEMU coding standards")

on its description: basically two regexes from Perl code would need changes:

        -       if (/\s*([\w\s]+?)(\(\))?\s*-/) {
        +       if (/\s*([\w\s]+?)(\s*-|:)/) {

and:
        -       if (/-(.*)/) {
        +       if (/[-:](.*)/) {

If I'm not mistaken, I got rid of the second regex during rewrite,
but I might be wrong. If I recall correctly, with Python code, the
change would be aon a single place at scripts/lib/kdoc/kdoc_parser.py:

	doc_sect = doc_com + \
-	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
+	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*[:-]([^:].*)?$',
	           flags=re.I, cache=False)

btw, the [^:] pattern there seems to be trying to avoid catching
"::". With the new proposed regex, and if "::" is something that we
need to avoid, if one uses "-:", it would miss the description. 
I guess that's ok.

From my side, I'm OK with the new regex, but one has to verify if
this won't cause unwanted side-effects.

Regards,
Mauro

Re: about make mandocs warnings

[Randy Dunlap]

Hi Mauro,

On 10/26/25 4:59 AM, Mauro Carvalho Chehab wrote:
> Em Sat, 25 Oct 2025 16:49:21 -0700
> Randy Dunlap <rdunlap@infradead.org> escreveu:
> 
>> Hi Mauro,
>>
>>
>> 'make mandocs' on the full kernel tree generates a little over 10,000
>> lines of Warning:s.  Then it says:
>>   Warning: kernel-doc returned 138 warnings
>>
>> What does that number mean?
> 
> Basically, at kdoc_files, we have:
> 
>     def warning(self, msg):
>         """Ancillary routine to output a warning and increment error count"""
> 
>         self.config.log.warning(msg)
>         self.errors += 1
> 
>     def error(self, msg):
>         """Ancillary routine to output an error and increment error count"""
> 
>         self.config.log.error(msg)
>         self.errors += 1
> 
> And kernel-doc itself exits with:
> 
> 	error_count = kfiles.errors
> 	sys.exit(error_count)

Oh, the warnings message comes from sphinx-build-wrapper.

> I guess the problem here is that POSIX exit codes are 8 bits only, so
> it ends reporting a wrong number of errors. Not sure what would be the
> best way to fix it.

and it's modulo 256, so exiting with 256 looks like exiting with 0.
Maybe just limit the number of warnings reported to 255 if it is > 255,
with a note in the source code.

>> kernel-doc is doing a very good job at finding issues in kernel-doc
>> notation, but there are a few cases of erroneous reporting. These are not
>> numerous and may not be worth much effort to fix them, although
>> some of them should not take much effort (I think). But I am just
>> reporting these in case someone wants to fix them.
>>
>>
>> Examples:
>>
>> Warning: drivers/misc/vmw_balloon.c:259 struct member '5' not described in 'vmballoon_batch_entry'
>> "5" is part of an expression "PAGE_SHIFT - 5" for number of bits in a bitfield:
>> struct vmballoon_batch_entry {
>> 	u64 status : 5;
>> 	u64 reserved : PAGE_SHIFT - 5;
>> 	u64 pfn : 52;
>> } __packed;
> 
> Fixing this one could be tricky, if we want to allow math expressions 
> at the regex, but sounds doable.
> 
>>
>> Warning: net/netfilter/nft_set_pipapo.h:102 union member '32' not described in 'nft_pipapo_map_bucket'
>> "32" is part of a static_assert() expression. Probably just
>> ignore the entire static_assert() [any number of lines].
> 
> Yeah.
> 
>> Warning: include/linux/hrtimer_types.h:47 Invalid param: enum hrtimer_restart            (*__private function)(struct hrtimer *)
>> Warning: include/linux/hrtimer_types.h:47 struct member 'enum hrtimer_restart            (*__private function' not described in 'hrtimer'
>> "__private" is an attribute from <linux/compiler_types.h> and the
>> struct member here should be "function", which is described.
>>
>>
>> Warning: include/linux/rethook.h:38 Invalid param: void (__rcu *handler) (struct rethook_node *, void *, unsigned long, struct pt_regs *)
>> Warning: include/linux/rethook.h:38 struct member 'void (__rcu *handler' not described in 'rethook'
>> "__rcu" is an attribute from <linux/compiler_types.h> and the
>> struct member here is "handler", which is described.
>>
>> Warning: security/ipe/hooks.c:54 function parameter '__always_unused' not described in 'ipe_mmap_file'
>> Warning: security/ipe/hooks.c:82 function parameter '__always_unused' not described in 'ipe_file_mprotect'
>> "__always_unused" is an attribute from <linux/compiler_attributes.h>.
>>
> 
> Probably all we need for the above is to add one line for each,
> to ignore the above macros.
> 
>>
>> Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent1)[LANDLOCK_NUM_ACCESS_FS]
>> Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent1' not described in 'is_access_to_paths_allowed'
>> Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent2)[LANDLOCK_NUM_ACCESS_FS]
>> Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent2' not described in 'is_access_to_paths_allowed'
>> @layer_masks_parent1 and @layer_masks_parent2 are described in kernel-doc.
>>
>> Warning: security/landlock/fs.c:1142 Invalid param: layer_mask_t (*const layer_masks_dom)[LANDLOCK_NUM_ACCESS_FS]
>> Warning: security/landlock/fs.c:1142 function parameter 'layer_mask_t (*const layer_masks_dom' not described in 'collect_domain_accesses'
>> @layer_masks_dom is described in kernel-doc.
>>
>>
>> Warning: security/landlock/ruleset.c:210 Invalid param: const struct landlock_layer (*const layers)[]
>> Warning: security/landlock/ruleset.c:210 function parameter 'const struct landlock_layer (*const layers' not described in 'insert_rule'
>> @layers is described in kernel-doc.
>>
>> Warning: security/landlock/ruleset.c:693 Invalid param: layer_mask_t (*const layer_masks)[]
>> Warning: security/landlock/ruleset.c:693 function parameter 'layer_mask_t (*const layer_masks' not described in 'landlock_init_layer_masks'
>> @layer_masks is described in kernel-doc.
> 
> These would require some extra logic - or a fix at an existing one - to 
> better handle parenthesis on arguments.
> 
>> Note: hundreds (probably thousands) of the mandocs warnings would disappear
>> if kernel-doc accepted '-' in addition to ':' as a function parameter
>> or struct/union/enum member separator (like it does for
>> function/struct/union/enum short description).
> 
> This is easy to fix, and QEMU has a patch mentioning what is needed
> at:
> 	9cbe72b868b7 ("scripts/kernel-doc: tweak for QEMU coding standards")
> 
> on its description: basically two regexes from Perl code would need changes:
> 
>         -       if (/\s*([\w\s]+?)(\(\))?\s*-/) {
>         +       if (/\s*([\w\s]+?)(\s*-|:)/) {
> 
> and:
>         -       if (/-(.*)/) {
>         +       if (/[-:](.*)/) {
> 
> If I'm not mistaken, I got rid of the second regex during rewrite,
> but I might be wrong. If I recall correctly, with Python code, the
> change would be aon a single place at scripts/lib/kdoc/kdoc_parser.py:
> 
> 	doc_sect = doc_com + \
> -	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
> +	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*[:-]([^:].*)?$',
> 	           flags=re.I, cache=False)
> 
> btw, the [^:] pattern there seems to be trying to avoid catching
> "::". With the new proposed regex, and if "::" is something that we
> need to avoid, if one uses "-:", it would miss the description. 
> I guess that's ok.
> 
> From my side, I'm OK with the new regex, but one has to verify if
> this won't cause unwanted side-effects.

Yes, for sure. I'm willing to do some testing on a patch.
Should I begin with the KernRe() change above?Thanks for your comments.
-- 
~Randy

Re: about make mandocs warnings

[Mauro Carvalho Chehab]

Em Sun, 26 Oct 2025 09:43:34 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi Mauro,
> 
> On 10/26/25 4:59 AM, Mauro Carvalho Chehab wrote:
> > Em Sat, 25 Oct 2025 16:49:21 -0700
> > Randy Dunlap <rdunlap@infradead.org> escreveu:
> >   
> >> Hi Mauro,
> >>
> >>
> >> 'make mandocs' on the full kernel tree generates a little over 10,000
> >> lines of Warning:s.  Then it says:
> >>   Warning: kernel-doc returned 138 warnings
> >>
> >> What does that number mean?  
> > 
> > Basically, at kdoc_files, we have:
> > 
> >     def warning(self, msg):
> >         """Ancillary routine to output a warning and increment error count"""
> > 
> >         self.config.log.warning(msg)
> >         self.errors += 1
> > 
> >     def error(self, msg):
> >         """Ancillary routine to output an error and increment error count"""
> > 
> >         self.config.log.error(msg)
> >         self.errors += 1
> > 
> > And kernel-doc itself exits with:
> > 
> > 	error_count = kfiles.errors
> > 	sys.exit(error_count)  
> 
> Oh, the warnings message comes from sphinx-build-wrapper.
> 
> > I guess the problem here is that POSIX exit codes are 8 bits only, so
> > it ends reporting a wrong number of errors. Not sure what would be the
> > best way to fix it.  
> 
> and it's modulo 256, so exiting with 256 looks like exiting with 0.
> Maybe just limit the number of warnings reported to 255 if it is > 255,
> with a note in the source code.
> 
> >> kernel-doc is doing a very good job at finding issues in kernel-doc
> >> notation, but there are a few cases of erroneous reporting. These are not
> >> numerous and may not be worth much effort to fix them, although
> >> some of them should not take much effort (I think). But I am just
> >> reporting these in case someone wants to fix them.
> >>
> >>
> >> Examples:
> >>
> >> Warning: drivers/misc/vmw_balloon.c:259 struct member '5' not described in 'vmballoon_batch_entry'
> >> "5" is part of an expression "PAGE_SHIFT - 5" for number of bits in a bitfield:
> >> struct vmballoon_batch_entry {
> >> 	u64 status : 5;
> >> 	u64 reserved : PAGE_SHIFT - 5;
> >> 	u64 pfn : 52;
> >> } __packed;  
> > 
> > Fixing this one could be tricky, if we want to allow math expressions 
> > at the regex, but sounds doable.
> >   
> >>
> >> Warning: net/netfilter/nft_set_pipapo.h:102 union member '32' not described in 'nft_pipapo_map_bucket'
> >> "32" is part of a static_assert() expression. Probably just
> >> ignore the entire static_assert() [any number of lines].  
> > 
> > Yeah.
> >   
> >> Warning: include/linux/hrtimer_types.h:47 Invalid param: enum hrtimer_restart            (*__private function)(struct hrtimer *)
> >> Warning: include/linux/hrtimer_types.h:47 struct member 'enum hrtimer_restart            (*__private function' not described in 'hrtimer'
> >> "__private" is an attribute from <linux/compiler_types.h> and the
> >> struct member here should be "function", which is described.
> >>
> >>
> >> Warning: include/linux/rethook.h:38 Invalid param: void (__rcu *handler) (struct rethook_node *, void *, unsigned long, struct pt_regs *)
> >> Warning: include/linux/rethook.h:38 struct member 'void (__rcu *handler' not described in 'rethook'
> >> "__rcu" is an attribute from <linux/compiler_types.h> and the
> >> struct member here is "handler", which is described.
> >>
> >> Warning: security/ipe/hooks.c:54 function parameter '__always_unused' not described in 'ipe_mmap_file'
> >> Warning: security/ipe/hooks.c:82 function parameter '__always_unused' not described in 'ipe_file_mprotect'
> >> "__always_unused" is an attribute from <linux/compiler_attributes.h>.
> >>  
> > 
> > Probably all we need for the above is to add one line for each,
> > to ignore the above macros.
> >   
> >>
> >> Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent1)[LANDLOCK_NUM_ACCESS_FS]
> >> Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent1' not described in 'is_access_to_paths_allowed'
> >> Warning: security/landlock/fs.c:765 Invalid param: layer_mask_t (*const layer_masks_parent2)[LANDLOCK_NUM_ACCESS_FS]
> >> Warning: security/landlock/fs.c:765 function parameter 'layer_mask_t (*const layer_masks_parent2' not described in 'is_access_to_paths_allowed'
> >> @layer_masks_parent1 and @layer_masks_parent2 are described in kernel-doc.
> >>
> >> Warning: security/landlock/fs.c:1142 Invalid param: layer_mask_t (*const layer_masks_dom)[LANDLOCK_NUM_ACCESS_FS]
> >> Warning: security/landlock/fs.c:1142 function parameter 'layer_mask_t (*const layer_masks_dom' not described in 'collect_domain_accesses'
> >> @layer_masks_dom is described in kernel-doc.
> >>
> >>
> >> Warning: security/landlock/ruleset.c:210 Invalid param: const struct landlock_layer (*const layers)[]
> >> Warning: security/landlock/ruleset.c:210 function parameter 'const struct landlock_layer (*const layers' not described in 'insert_rule'
> >> @layers is described in kernel-doc.
> >>
> >> Warning: security/landlock/ruleset.c:693 Invalid param: layer_mask_t (*const layer_masks)[]
> >> Warning: security/landlock/ruleset.c:693 function parameter 'layer_mask_t (*const layer_masks' not described in 'landlock_init_layer_masks'
> >> @layer_masks is described in kernel-doc.  
> > 
> > These would require some extra logic - or a fix at an existing one - to 
> > better handle parenthesis on arguments.
> >   
> >> Note: hundreds (probably thousands) of the mandocs warnings would disappear
> >> if kernel-doc accepted '-' in addition to ':' as a function parameter
> >> or struct/union/enum member separator (like it does for
> >> function/struct/union/enum short description).  
> > 
> > This is easy to fix, and QEMU has a patch mentioning what is needed
> > at:
> > 	9cbe72b868b7 ("scripts/kernel-doc: tweak for QEMU coding standards")
> > 
> > on its description: basically two regexes from Perl code would need changes:
> > 
> >         -       if (/\s*([\w\s]+?)(\(\))?\s*-/) {
> >         +       if (/\s*([\w\s]+?)(\s*-|:)/) {
> > 
> > and:
> >         -       if (/-(.*)/) {
> >         +       if (/[-:](.*)/) {
> > 
> > If I'm not mistaken, I got rid of the second regex during rewrite,
> > but I might be wrong. If I recall correctly, with Python code, the
> > change would be aon a single place at scripts/lib/kdoc/kdoc_parser.py:
> > 
> > 	doc_sect = doc_com + \
> > -	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
> > +	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*[:-]([^:].*)?$',
> > 	           flags=re.I, cache=False)
> > 
> > btw, the [^:] pattern there seems to be trying to avoid catching
> > "::". With the new proposed regex, and if "::" is something that we
> > need to avoid, if one uses "-:", it would miss the description. 
> > I guess that's ok.
> > 
> > From my side, I'm OK with the new regex, but one has to verify if
> > this won't cause unwanted side-effects.  
> 
> Yes, for sure. I'm willing to do some testing on a patch.
> Should I begin with the KernRe() change above?

Yes.

> Thanks for your comments.

Anytime.

(sorry for not answering earlier... was in OOT solving some stuff
abroad)

Regards,
Mauro

Re: about make mandocs warnings (1)

[Randy Dunlap]

On 11/7/25 2:15 AM, Mauro Carvalho Chehab wrote:
> Em Sun, 26 Oct 2025 09:43:34 -0700
> Randy Dunlap <rdunlap@infradead.org> escreveu:
> 
>> Hi Mauro,
>>
>> On 10/26/25 4:59 AM, Mauro Carvalho Chehab wrote:
>>> Em Sat, 25 Oct 2025 16:49:21 -0700
>>> Randy Dunlap <rdunlap@infradead.org> escreveu:
>>>   
>>>> Hi Mauro,
>>>>
>>>>

[snip]

>>>> Note: hundreds (probably thousands) of the mandocs warnings would disappear
>>>> if kernel-doc accepted '-' in addition to ':' as a function parameter
>>>> or struct/union/enum member separator (like it does for
>>>> function/struct/union/enum short description).  
>>>
>>> This is easy to fix, and QEMU has a patch mentioning what is needed
>>> at:
>>> 	9cbe72b868b7 ("scripts/kernel-doc: tweak for QEMU coding standards")
>>>
>>> on its description: basically two regexes from Perl code would need changes:
>>>
>>>         -       if (/\s*([\w\s]+?)(\(\))?\s*-/) {
>>>         +       if (/\s*([\w\s]+?)(\s*-|:)/) {
>>>
>>> and:
>>>         -       if (/-(.*)/) {
>>>         +       if (/[-:](.*)/) {
>>>
>>> If I'm not mistaken, I got rid of the second regex during rewrite,
>>> but I might be wrong. If I recall correctly, with Python code, the
>>> change would be aon a single place at scripts/lib/kdoc/kdoc_parser.py:
>>>
>>> 	doc_sect = doc_com + \
>>> -	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
>>> +	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*[:-]([^:].*)?$',
>>> 	           flags=re.I, cache=False)
>>>
>>> btw, the [^:] pattern there seems to be trying to avoid catching
>>> "::". With the new proposed regex, and if "::" is something that we
>>> need to avoid, if one uses "-:", it would miss the description. 
>>> I guess that's ok.
>>>
>>> From my side, I'm OK with the new regex, but one has to verify if
>>> this won't cause unwanted side-effects.  
>>
>> Yes, for sure. I'm willing to do some testing on a patch.
>> Should I begin with the KernRe() change above?
> 
> Yes.

first report with the one-line change to KernRe() above:

$ ./scripts/kernel-doc.py -none -Wall sound/soc/codecs/cs-amp-lib.c
Warning: sound/soc/codecs/cs-amp-lib.c:574 duplicate section name 'Return'
Warning: sound/soc/codecs/cs-amp-lib.c:574 duplicate section name 'Return'

Without the KernRe() change, these are not reported (which is correct).
The new/changed line finds "*\s*[Rr]eturn" in a comment (without a trailing ':')
and considers it to be a Return: section.


> (sorry for not answering earlier... was in OOT solving some stuff
> abroad)

Sure, not a problem.

-- 
~Randy

Re: about make mandocs warnings (1)

[Randy Dunlap]

On 11/7/25 1:33 PM, Randy Dunlap wrote:
> 
> 
> On 11/7/25 2:15 AM, Mauro Carvalho Chehab wrote:
>> Em Sun, 26 Oct 2025 09:43:34 -0700
>> Randy Dunlap <rdunlap@infradead.org> escreveu:
>>
>>> Hi Mauro,
>>>
>>> On 10/26/25 4:59 AM, Mauro Carvalho Chehab wrote:
>>>> Em Sat, 25 Oct 2025 16:49:21 -0700
>>>> Randy Dunlap <rdunlap@infradead.org> escreveu:
>>>>   
>>>>> Hi Mauro,
>>>>>
>>>>>
> 
> [snip]
> 
>>>>> Note: hundreds (probably thousands) of the mandocs warnings would disappear
>>>>> if kernel-doc accepted '-' in addition to ':' as a function parameter
>>>>> or struct/union/enum member separator (like it does for
>>>>> function/struct/union/enum short description).  
>>>>
>>>> This is easy to fix, and QEMU has a patch mentioning what is needed
>>>> at:
>>>> 	9cbe72b868b7 ("scripts/kernel-doc: tweak for QEMU coding standards")
>>>>
>>>> on its description: basically two regexes from Perl code would need changes:
>>>>
>>>>         -       if (/\s*([\w\s]+?)(\(\))?\s*-/) {
>>>>         +       if (/\s*([\w\s]+?)(\s*-|:)/) {
>>>>
>>>> and:
>>>>         -       if (/-(.*)/) {
>>>>         +       if (/[-:](.*)/) {
>>>>
>>>> If I'm not mistaken, I got rid of the second regex during rewrite,
>>>> but I might be wrong. If I recall correctly, with Python code, the
>>>> change would be aon a single place at scripts/lib/kdoc/kdoc_parser.py:
>>>>
>>>> 	doc_sect = doc_com + \
>>>> -	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*:([^:].*)?$',
>>>> +	    KernRe(r'\s*(@[.\w]+|@\.\.\.|' + known_section_names + r')\s*[:-]([^:].*)?$',
>>>> 	           flags=re.I, cache=False)
>>>>
>>>> btw, the [^:] pattern there seems to be trying to avoid catching
>>>> "::". With the new proposed regex, and if "::" is something that we
>>>> need to avoid, if one uses "-:", it would miss the description. 
>>>> I guess that's ok.
>>>>
>>>> From my side, I'm OK with the new regex, but one has to verify if
>>>> this won't cause unwanted side-effects.  
>>>
>>> Yes, for sure. I'm willing to do some testing on a patch.
>>> Should I begin with the KernRe() change above?
>>
>> Yes.
> 
> first report with the one-line change to KernRe() above:
> 
> $ ./scripts/kernel-doc.py -none -Wall sound/soc/codecs/cs-amp-lib.c
> Warning: sound/soc/codecs/cs-amp-lib.c:574 duplicate section name 'Return'
> Warning: sound/soc/codecs/cs-amp-lib.c:574 duplicate section name 'Return'
> 
> Without the KernRe() change, these are not reported (which is correct).
> The new/changed line finds "*\s*[Rr]eturn" in a comment (without a trailing ':')
> and considers it to be a Return: section.

I have compared about 30% of the "make mandocs" output from before/after
this patch. This "Return" issue is the only problem that I have found so far
and I have seen it in several other files.

The "accept ':'  or '-' for parameter separator" is working fine so far
for the places that it should work.

-- 
~Randy