Re: [PATCH net-next v3 1/3] net: phylink: provide phylink_mac_implements_lpi()

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

On Mon, Feb 10, 2025 at 03:20:54PM +0200, Vladimir Oltean wrote:
> On Mon, Feb 10, 2025 at 10:36:44AM +0000, Russell King (Oracle) wrote:
> > diff --git a/include/linux/phylink.h b/include/linux/phylink.h
> > index 898b00451bbf..0de78673172d 100644
> > --- a/include/linux/phylink.h
> > +++ b/include/linux/phylink.h
> > @@ -737,6 +737,18 @@ static inline int phylink_get_link_timer_ns(phy_interface_t interface)
> >  	}
> >  }
> >  
> > +/**
> > + * phylink_mac_implements_lpi() - determine if MAC implements LPI ops
> > + * @ops: phylink_mac_ops structure
> > + *
> > + * Returns true if the phylink MAC operations structure indicates that the
> > + * LPI operations have been implemented, false otherwise.
> 
> This is something that I only noticed for v3 because I wanted to leave a
> review tag, so I first checked the status in patchwork, but there it says:
> 
> include/linux/phylink.h:749: warning: No description found for return value of 'phylink_mac_implements_lpi'
> 
> I am aware of this conversation from November where you raised the point
> about tooling being able to accept the syntax without the colon as well:
> https://lore.kernel.org/netdev/87v7wjffo6.fsf@trenco.lwn.net/
> 
> but it looks like it didn't go anywhere, with Jon still preferring the
> strict syntax for now, and no follow-up that I can see. So, the current
> conventions are not these, and you haven't specifically said anywhere
> that you are deliberately ignoring them.

It was explained in this email as part of that thread:

https://lore.kernel.org/netdev/ZzjHH-L-ylLe0YhU@shell.armlinux.org.uk/

The reason is that it goes against natural grammar. The only time that
"Returns:" would make sense in grammar is when listing with e.g. a
bulleted list, where the part before the colon doesn't have to be a
complete sentence.

This is why it's going to be an uphill battle - grammatically it is
wrong, and thus it doesn't flow when thinking about documenting the
return value.

If we want to go to a bulleted list, then it will be natural to add
the colon.

I'm not going to explain to this level of detail in every email, and
because of the grammatical nature of this, it's going to be very
difficult to use a form that goes against proper grammar.

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