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

["Russell King (Oracle)" <linux@armlinux.org.uk>]

On Thu, Jan 02, 2025 at 11:01:54AM -0700, Jonathan Corbet wrote:
> "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.

Right, so we're at logger-heads. Someone needs to give.

Either:

1) kernel-doc gets fixed

2) we accept that we have to work around kernel-doc to decently document
   function pointers, and while it may not be great, it gives _full_ and
   complete documentation of the function pointer.

3) we don't document function pointers at all (which leads to users not
   having something to read when implementing those methods, and
   reviewers having to post boiler plate explanations of the function
   pointers when reviewing patches... or just give up with trying to
   get people to implement the methods sanely.)

I'll leave it to others to decide which they want to do, but I'm
intending to continue with (2) for phylink, because I believe that has
the most benefit to the community, even though it is sub-optimal.

If one looks at:

https://kernel.org/doc/html/v6.13-rc5/networking/kapi.html#c.phylink_mac_ops

then one can see there is a _heck_ of a lot of valuable detail
documented against each of the function pointers - and I have no
intention what so ever to get rid of that.

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!