Re: README.md files per directory

Alexander Leidinger <[email protected]> writes:

> 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.

I'd be glad to see something like [1], but officially supported by the
project.

Regards,
Dmitry

[1] https://elixir.bootlin.com/freebsd/v15.0/source

-- 
https://wiki.freebsd.org/DmitrySalychev