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 02:05:58PM +0000, Russell King (Oracle) wrote:
> 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.

Also note that it follows the style already present in that file
with one exception (which is one of the few cases I remembered to use
the new format.)

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