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

[Andrew Lunn]

On Mon, Dec 04, 2023 at 06:17:52PM -0800, Jakub Kicinski wrote:
> On Tue, 28 Nov 2023 14:36:30 +0100 Christian Marangi wrote:
> > +/**
> > + * phy_package_write_mmd - Convenience function for writing a register
> > + * on an MMD on a given PHY using the PHY package base addr, added of
> > + * the addr_offset value.
> > + * @phydev: The phy_device struct
> > + * @addr_offset: The offset to be added to PHY package base_addr
> > + * @devad: The MMD to read from
> > + * @regnum: The register on the MMD to read
> > + * @val: value to write to @regnum
> > + *
> > + * Same rules as for phy_write();
> > + *
> > + * NOTE: It's assumed that the entire PHY package is either C22 or C45.
> > + */
> 
> > +/*
> > + * phy_package_write_mmd - Convenience function for writing a register
> > + * on an MMD on a given PHY using the PHY package base addr, added of
> > + * the addr_offset value.
> > + */
> > +int phy_package_write_mmd(struct phy_device *phydev,
> > +			  unsigned int addr_offset, int devad,
> > +			  u32 regnum, u16 val);
> 
> Hm, I see there's some precedent here already for this duplicated
> semi-kdoc. It seems a bit unusual. If I was looking for kdoc and 
> found the header one I'd probably not look at the source file at all.
> 
> Andrew, WDYT?

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.

      Andrew