Re: [PATCH net-next v1 1/1] net: phy: Move callback comments from struct to kernel-doc section

[Jonathan Corbet <corbet@lwn.net>]

"Russell King (Oracle)" <linux@armlinux.org.uk> writes:

> This is the fundamental problem with kernel-doc, when it's missing
> something that really should already be there. It's not like we're
> the first to use function pointers in structs - that's a thing that
> the kernel has been doing for decades.

Unfortunately, kernel-doc is a gnarly collection of Perl regexes that
first appeared in 2.3.52pre1 some 25 years ago and has only grown more
gnarly since.

> I also have no desire to attempt to fix kernel-doc -

Neither does anybody else.  There are a few of us who will mount an
expedition into those dark woods on occasion to fix something, but there
is little desire on any part to make significant improvements, including
adding things that should already be there.  It's just barely
maintainable.

The proper solution is to reimplement kernel-doc in a language that
people actually want to deal with, cleaning out 25 years of cruft in the
process.  One way to do that would be to bring that functionality
directly into our Sphinx extension, rewriting it in Python.  An
alternative I have been considering, as a learning project that would
make me One Of The Cool Kids again, would be to do it in Rust instead.

For the time being, though, I wouldn't hold my breath for getting this
kind of improvement into kernel-doc.  I wish I could say otherwise.

Thanks,

jon