Re: README.md files per directory

On Fri, Apr 17, 2026 at 2:44 PM Dmitry Salychev <[email protected]> wrote:

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

So it can be hard to know where to add these, and how to keep them
up-to-date.

Having said that, I think it's generally a good idea, for content that's not
overly simplistic.

Warner


> Regards,
> Dmitry
>
> [1] https://elixir.bootlin.com/freebsd/v15.0/source
>
> --
> https://wiki.freebsd.org/DmitrySalychev
>
>