lists.openwall.net   lists  /  announce  owl-users  owl-dev  john-users  john-dev  passwdqc-users  yescrypt  popa3d-users  /  oss-security  kernel-hardening  musl  sabotage  tlsify  passwords  /  crypt-dev  xvendor  /  Bugtraq  Full-Disclosure  linux-kernel  linux-netdev  linux-ext4  linux-hardening  linux-cve-announce  PHC 
Open Source and information security mailing list archives
 
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <ZW9LroqqugXzqAY9@shell.armlinux.org.uk>
Date: Tue, 5 Dec 2023 16:11:26 +0000
From: "Russell King (Oracle)" <linux@...linux.org.uk>
To: Jakub Kicinski <kuba@...nel.org>
Cc: Andrew Lunn <andrew@...n.ch>, Christian Marangi <ansuelsmth@...il.com>,
	Florian Fainelli <florian.fainelli@...adcom.com>,
	Broadcom internal kernel review list <bcm-kernel-feedback-list@...adcom.com>,
	Heiner Kallweit <hkallweit1@...il.com>,
	"David S. Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>, Paolo Abeni <pabeni@...hat.com>,
	David Epping <david.epping@...singlinkelectronics.com>,
	Vladimir Oltean <olteanv@...il.com>,
	Harini Katakam <harini.katakam@....com>, netdev@...r.kernel.org,
	linux-kernel@...r.kernel.org, workflows@...r.kernel.org
Subject: Re: [net-next PATCH v3 3/3] net: phy: add support for PHY package
 MMD read/write

On Tue, Dec 05, 2023 at 07:29:12AM -0800, Jakub Kicinski wrote:
> On Tue, 5 Dec 2023 15:10:50 +0000 Russell King (Oracle) wrote:
> > 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.
> 
> Plus I think people using IDEs (i.e. not me) may use the "jump to
> definition" functionality, to find the doc? 
> 
> TBH I thought putting kdoc in the C source was documented in the coding
> style, but I can't find any mention of it now.

Well, in Documentation/doc-guide/kernel-doc.rst:

  The function and type kernel-doc comments should be placed just before
  the function or type being described in order to maximise the chance
  that somebody changing the code will also change the documentation.

That implies (but not explicitly) that it should be at the function
definition site, since "changing the code" is used as an argument as
I did in my previous email.

Secondly, this document goes on to give an example of running
scripts/kernel-doc on a .c file.

Thirdly, there are seven references in this document of kernel-doc
in .c files, and only one for kernel-doc in a .h file. So this suggests
that "it will be in a .c file" isn't a rule (it can't be because of
documenting structures!)

So let's not get hung up on whether it should be in .c or .h because I
think that isn't relevant. Instead, I think it's about "it should be at
the definition site" - that being a structure definition or a function
definition, and not at a function prototype.

The only exception I can think of is the style I've used in
linux/phylink.h for the _method_ definitions which look like function
prototypes - that's just a work-around because one can't kernel-doc
the structure-of-function-pointers and document the function parameters
without jumping through that hoop, and it would be silly to document
the methods in some random driver!

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

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ