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

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] [day] [month] [year] [list]

Message-ID: <a3572abc-b49a-44e7-b36c-cf462bcc09ac@lunn.ch>
Date: Tue, 5 Dec 2023 21:11:00 +0100
From: Andrew Lunn <andrew@...n.ch>
To: Jeff Johnson <quic_jjohnson@...cinc.com>
Cc: "Russell King (Oracle)" <linux@...linux.org.uk>,
	Jakub Kicinski <kuba@...nel.org>,
	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

> Having worked with closed-source systems, especially VxWorks, for many
> years (where the header files contain all the documentation), it just
> seems strange to embed the documentation in the .c files.

The key words here might be closed-source. With such black boxes, you
don't have access the sources. You cannot look at the source to
understand how a function works. In the open source world, the
comments partially function as an introduction to reading the code and
understanding what it does. You are also encouraged to change the code
if needed, which in the closed source world you cannot do.

Given this discussion, i now think putting the documentation in the .c
file makes more sense. For the generated documentation it does not
matter, but for the reader of the code, having it in the .c files does
seem to make sense.

     Andrew