linux-kernel - Re: [PATCH] scripts/kernel-doc: drop "

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250606005051.60a48cb4@foz.lan>
Date: Fri, 6 Jun 2025 00:50:51 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Matthew Wilcox <willy@...radead.org>
Cc: Jonathan Corbet <corbet@....net>, Randy Dunlap <rdunlap@...radead.org>,
 linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org, Andrew Morton
 <akpm@...ux-foundation.org>, Suren Baghdasaryan <surenb@...gle.com>, Mauro
 Carvalho Chehab <mchehab@...nel.org>
Subject: Re: [PATCH] scripts/kernel-doc: drop "_noprof" on function
 prototypes

Em Thu, 5 Jun 2025 20:31:02 +0100
Matthew Wilcox <willy@...radead.org> escreveu:

> On Thu, Jun 05, 2025 at 01:18:50PM -0600, Jonathan Corbet wrote:
> > Matthew Wilcox <willy@...radead.org> writes:  
> > > This turns out not to be enough.  For example, krealloc() is
> > > currently undocumented.  This is because we match the function name
> > > in EXPORT_SYMBOL() against the function name in the comment, and they
> > > don't match.  This patch restores the documentation, although only
> > > for the python version of kernel-doc, and I'm pretty sure there's a
> > > better way to do it (eg building it into the export_symbol* regexes).
> > > I can turn this into a proper patch if this is the way to go, but for
> > > now it's just to illustrate the problem.  
> > 
> > FWIW, I have no problem with leaving the perl version behind, I expect
> > we'll drop it in 6.17.

I agree with Jon: it is time to retire the perl version. 

> > 
> > (Meanwhile I don't object to your fix as a short-term workaround)  
> 
> OK, will give Mauro 24 hours to comment, then resend as a patch if
> there are no objections.
> 
> > We see other variants of this problem out there, where we want to
> > document foo(), but that's really just a macro calling _foo(), where the
> > real code is.

The problem is that one may want to document both _foo() and foo(),
if they have different arguments. I'm pretty sure we have cases like
that.

> > 
> > I wonder if we could add some sort of a marker to the kerneldoc comment
> > saying "we are documenting foo(), but do you checks against _foo()"
> > instead?  That would be more general than trying to keep a list of
> > suffixes to hack off.  
> 
> kernel-doc is our own format, so sure, we can add whatever marker
> we want to it.  I think it's not quite general enough because we have
> situations like:
> 
> static inline void foo(int x)
> {
> 	numa_foo(x, NUMA_NO_NODE);
> };
> 
> /**
>  * foo - Frobnicate
>  * @x: How many
>  * @nid: Which node
>  */
> void numa_foo(int x, int node)
> { .. }

If I"m not mistaken, if you do things like that, kernel-doc.py will
complain that "foo" is not "numa_foo". It will also complain that
"nid" doesn't exist and "node" is not documented.

Basically, there is a strict check there (if it got properly 
backported from the Perl version) which checks if kernel-doc
is documenting the next function prototype name and argument
names.

The rationale is that we caught several cases where a function was
removed, renamed and/or have their parameters renamed without the
corresponding kernel-doc change. So, the verification is now
stricter (*). When we enabled such check, we fixed several bad
kernel-doc markups.

(*) Also, kernel-doc handles files in one pass at read time,
    sequentially. It could be possible to change it, but kernel-doc 
    is already complex enough, and placing the markup just before
    the function is a good practice anyway.

> and now we're documenting a parameter that doesn't exist.  The only
> solution is to move the kdoc to the header file, which is annoying for
> everyone.  Or replicate the declaration in the C file and kdoc it there.

Heh, for my taste, having kernel-docs at header files look better, as
this is where the kAPIs should be defined anyway. 

Ok, one may change the behavior of a function without touching the
arguments and forget to update kernel-doc at the header files to tell
about such change, but this is problematic anyway, as, if someone is
relying on a certain behavior of a kAPI function, changing its behavior
may result on unexpected results at the current callers - and even
future callers.

Thanks,
Mauro