Re: [net-next PATCH v3 3/3] net: phy: add support for PHY package MMD read/write

[Russell King (Oracle)]

On Tue, Dec 05, 2023 at 03:54:04PM +0100, Andrew Lunn wrote:
> > > I tend to agree. These functions should be documented once in kdoc,
> > > and only once. I don't really care if its in the header, or the C
> > > code, but not both.
> > >
> > 
> > Ok just to make sure, I should keep the kdoc in the .c and drop them in
> > .h ? (or should I move the more complete kdoc in .c to .h and remove
> > kdoc in .c?)
> 
> Please put the kdoc in the header file and remove if from the .c file.

phy-core.c follows the style that the kdoc is in the .c file rather
than the header file.

I've raised this before in other subsystems, and it's suggested that
it's better to have it in the .c file. I guess the reason is that it's
more obvious that the function is documented when modifying it, so
there's a higher probability that the kdoc will get updated when the
function is altered.

I guess a question to ask is how often do people modify a function and
then check the header for any documentation?

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