Re: [PATCH 0/2] Move kernel-doc to tools/docs

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

Em Sat, 17 Jan 2026 10:09:56 -0800
Randy Dunlap <rdunlap@infradead.org> escreveu:

> On 1/17/26 2:00 AM, Mauro Carvalho Chehab wrote:
> > Em Fri, 16 Jan 2026 10:48:51 -0700
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >   
> >> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> >>  
> >>> Em Wed, 14 Jan 2026 12:24:31 -0700
> >>> Jonathan Corbet <corbet@lwn.net> escreveu:
> >>>    
> >>>> Randy Dunlap <rdunlap@infradead.org> writes:
> >>>>     
> >>>>> I do many of these on a regular basis:
> >>>>>
> >>>>> $ ./scripts/kernel-doc -none -Wall <path_to_source_file>
> >>>>>
> >>>>> Will I still be able to do that (by using ./tools/doc/kernel-doc ...)?      
> >>>>
> >>>> Yes.  The tool moves, but its functionality remains unchanged.    
> >>>
> >>> That's actually a good point: should we preserve a link on scripts
> >>> pointing to ../tools/doc/kernel-doc? I suspect that a change like
> >>> that could break some machinery on several CI tools and scripts
> >>> out there. If so, it could be useful to keep a link - at least for
> >>> a couple of kernel releases.    
> >>
> >> So is the location of kernel-doc part of our ABI, or an internal detail?
> >> :)  
> > 
> > Surely it is not part of ABI: it can be changed whenever we want.
> > 
> > From my side, I don't mind where it is located: it will take some
> > time, but my fingers will end learning its new location/name ;-)
> >   
> >> I'm not deeply opposed to maintaining the symlink, though I'd rather
> >> not.  It won't be for "a couple of releases", though; if the symlink is
> >> there, nothing will ever change.  
> > 
> > I see two reasons why having a symlink:
> > 
> > 1. to avoid the risk of eventually breaking someone's CI or scripts.
> >    This is just a preventive measure, as I'm not aware of anyone
> >    with such scripts;  
> 
> I have some such scripts. And it's easy to update them, but I'd like for them
> to be compatible both going forward and backward in kernel versions -- without
> having to do something like:
> 
> 	if [ -x scripts/kernel-doc ]; then
> 		foo
> 	elif [ -x tools/docs/kernel-doc ]; then
> 		baz
> 	else { help; }
> 
> I doubt that I am unique/alone in this.
> 
> > 2. as you don't want ".py" extension on execs, but PEP8 mandates it, 
> >    together with replacing "-" with "_", you can have a symlink that
> >    would make both PEP8 and you happy ;-)

Just to be clear, when I'm talking about PEP8, I'm actually referring
to the language support for import a python code with "import" and "from". 

The rationale is that some day we may end needing using autodoc(*), or
some other Sphinx extension that would require it, like argparse ones:

	https://sphinxcontrib-autoprogram.readthedocs.io/en/stable/
	https://pypi.org/project/sphinxcontrib-autoprogram/

This would avoid the need of documenting some things twice: at the
code and at the documentation itself.

(*) Right now, we don't have any strong reasons to use autodoc on
    kernel-doc exec: the only possible reason on kernel-doc would be
    to avoid documenting return codes twice, but we could do it also
    via argparse, with something like:

	RETURN_CODE=deident("""
	    The return value is:

	    - 0: success or Python version is not compatible with
	      kernel-doc.  If -Werror is not used, it will also
	      return 0 if there are issues at kernel-doc markups;

	    - 1: an abnormal condition happened;

	    - 2: argparse issued an error;

	    - 3: if -Werror is used, and one or more unfiltered parse
		warnings happened.
	""")

	argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter,
                                description=DESC, epilog=RETURN_CODE)

    Eventually, it could be useful to use an argparse extension in
    the future, if we want to add the help output inside the
    auto-generated docs.

    Anyway, after having this series merged and mine fixing
    the issues with -Werror, I intend to send you a separate patch
    series with something like the above and moving MsgFormatter
    to a separate module.
	
Thanks,
Mauro