Em Thu, 5 Jun 2025 20:31:02 +0100
Matthew Wilcox <willy@xxxxxxxxxxxxx> escreveu:
> On Thu, Jun 05, 2025 at 01:18:50PM -0600, Jonathan Corbet wrote:
> > Matthew Wilcox <willy@xxxxxxxxxxxxx> 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
