Re: README.md files per directory

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