Re: README.md files per directory
Minsoo Choo <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.hackers |
|---|---|
| Message-ID | <k7Oc5mf3cr6eIomoMw0fXSDu0ZCx5YNFxMcn01a8PqowSaKO44yO9y4dXe3dvKXJK4M_f8Ecgu2EaPm0y11hfpLQULywLPl34AGidKws4eo=@proton.me> |
On Friday, April 17th, 2026 at 3:34 AM, 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. > > Thanks > -- > Farhan Khan > > > 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 -- Minsoo Choo