Re: README.md files per directory

Alexander Leidinger <[email protected]> Sun, 19 Apr 2026 14:45:54 +0200

Newsgroups	gmane.os.freebsd.devel.hackers
Organization	No organization, this is a private message.
Message-ID	<[email protected]>

Am 2026-04-18 18:15, schrieb Adrian Chadd:
> 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".

The /usr/src/tools/kerneldoc/subsys/ parts are taking source and header 
files into account. See FILE_PATTERNS in 
/usr/src/tools/kerneldoc/subsys/common-Doxyfile. Additionally you can 
specify any additional file to include in the config, see INPUT in 
/usr/src/tools/kerneldoc/subsys/Doxyfile-*.

Bye,
Alexander.

-- 
http://www.Leidinger.net [email protected]: PGP 0x8F31830F9F2772BF
http://www.FreeBSD.org    [email protected]  : PGP 0x8F31830F9F2772BF

signature.asc (application/pgp-signature, 833 B)