Re: about make mandocs warnings

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

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