Re: README.md files per directory
obiwac <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.hackers |
|---|---|
| Message-ID | <CAN8-kNUL9Ky2-iXThyAGcF6Pt453Ai-sJ4MZQUy5=uiXvDtz9w@mail.gmail.com> |
> Why would you do this manually? Just prefill en masse with AI and inspire people to vet the prose. I think the trouble caused by the potential errors AI would put in these docs is not worth the benefits this would bring. On Sat, 18 Apr 2026 at 19:18, Joe Schaefer <[email protected]> wrote: > > 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 >>