Re: README.md files per directory

Alexander Leidinger <[email protected]> Fri, 17 Apr 2026 20:12:04 +0200

Newsgroups	gmane.os.freebsd.devel.hackers
Organization	No organization, this is a private message.
Message-ID	<[email protected]>

Am 2026-04-17 19:03, schrieb Adrian Chadd:
> On Fri, 17 Apr 2026 at 01:44, David Chisnall <[email protected]> 
> wrote:
>> 
>> On 16 Apr 2026, at 19:48, Adrian Chadd <[email protected]> wrote:
>> >
>> > On Thu, 16 Apr 2026 at 11:34, Farhan Khan <[email protected]> wrote:
>> >>
>> >> Any thoughts on having README.md files in each directory? It would describe what the code was for, the maintainer, things that might help a would-be developer, status, TODOs, etc.
>> >>
>> >> There's some code I recently found that I had no idea what it was until I asked AI. It might also be useful in public code displayers, such as Github, Gitea, etc.
>> >
>> > Honestly I've wondered about potentially putting README.md files in
>> > places to basically be a "Design Doc" summary of the subsystem
>> > (notably net80211, but also describing ifnet and desired locking
>> > examples, how the USB stack functions, etc.)
>> >
>> > I don't think we have any guidelines about it yet.
>> 
>> It’s a good first step, but a lot of directories (particularly in the 
>> kernel) have a lot of files and a *very* scarce on comments.  I would 
>> love to have a policy that each file should start with a top-level 
>> comment explaining what the file is for and what the key abstractions 
>> are.  If you don’t already see the need for this: Pick a random file 
>> in the FreeBSD repository that you’ve never looked at before and see 
>> how long it takes you to figure out what it is for and why.
> 
> Yup, exactly.
> 
> I'll go noodle on this a bit and then go propose something to core /
> src and see what they think.

We have /usr/src/tools/kerneldoc/subsys which generates HTML or latex 
based docs for the kernel. Some parts of the kernel have already src 
comments in doxygen style which are used for this (e.g. 
https://www.leidinger.net/FreeBSD/dox/kern/html/d7/d56/group__DEVICE.html). 
Large parts of the kernel would benefit from adding more.

For "uncommented" src this gives an overview of what is available in the 
files. You can see that at https://www.leidinger.net/FreeBSD/dox/

Bye,
Alexander.

-- 
http://www.Leidinger.net [email protected]: PGP 0x8F31830F9F2772BF
http://www.FreeBSD.org    [email protected]  : PGP 0x8F31830F9F2772BF

signature.asc (application/pgp-signature, 833 B)