Re: README.md files per directory

On Sunday, April 19th, 2026 at 1:15 AM, 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
> 
> 

I tried kerndoc, but the output presented by Sphinx is quite ugly mostly due to misinterpreting macros. We might get better result with latest doxygen—the one we have write now is very outdated[1].

For subsystems I think README.md is sufficient, but there shouldn't be too many of them.

In the beginning of my coop term, I worked on .rst based documentation to mimic the Linux Kernel Documentation, but the issue was that our sphinx port was outdated as well IIRC.

[1] https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=279330