Re: README.md files per directory

Why would you do this manually? Just prefill en masse with AI and inspire
people to vet the prose.

The opposite never works with docs

On Sat, Apr 18, 2026 at 12:15 PM Adrian Chadd <[email protected]> wrote:

> On Fri, 17 Apr 2026 at 19:55, Minsoo Choo <[email protected]>
> wrote:
>
> >
> > I think we need that at least for stand/ and sys/, and sys/ already has
> a README.md. It's currently outdated (e.g. no mention on bsm/, dts/, isa/)
> and the ordering is broken (e.g. conf/ comes before compat/). I'll fix that
> this weekend.
> >
> > For individual file level, I think we need something like LLVM file
> headers [1] where file description comes after copyright notice. Currently
> we don't strictly follow Doxygen format for comments (e.g. function
> description), but converting existing comments to Doxygen format is now
> less tedious thanks to LLMs.
> >
> > I've always wished we move sys/amd64, sys/arm64... to sys/arch/<arch>
> like NetBSD does and do the same for other directories like lib/libc. But
> that might break existing revisions and future MFCs, so I'm not sure if
> every devs want that.
> >
> > [1] https://llvm.org/docs/CodingStandards.html#file-headers
>
> Do we have something written down somewhere on where/how to put what
> format doxygen stuff?
>
> And how's that work for subsystem descriptions? Are there files we can
> put them in that the tooling will pull out of or is it still "put it
> all in header files" ?
>
> eg I've been putting them in net80211 source files, but my experience
> in the past is that it pulls the API definitions from header files,
> not from .c source files.
> I've had the same problem in the past with headerdoc tools in ye olde
> days - the documentation when reading code makes a lot of sense to
> have
> with the functions themselves in the source file, but the tools really
> want to pull them from the header files. For Java style codebases
> where a majority
> of your definitions/code /are/ in the same file you ended up "just
> winning".
>
>
>
> -adrian
>
>