Hooray docs! Please consider using "relnotes: yes" for any new manuals, a fixes tag to attach it to the commit adding the driver so re can keep track of that more easily, and the manual as the object in the commit message instead of the driver ("apple_bce.4: add a basic manpage describing the driver").

share/man/man4/apple_bce.4
2–26	We updated the preferred license for new files, take a look. https://docs.freebsd.org/en/articles/license-guide/ Notably, the berne convention means that All rights reserved is the default state, ratified in 182 countries since 1989. The spdx tag lets us parse it mechanically and unambiguously and not have to reproduce it every single time in the tree. Also, it's an ISO spec so it's like, a real thing, and Linux is doing it too.
32	Most of the time we put driver at the end. It's shorter and since driver is implied by section 4, it makes apropos results cleaner in the same vein as we do commit messages "foo: Bar description".
34–47	We did the prose in SYNOPSIS thing for a while but it's really inconsistent with what SYNOPSIS means in every other section, and it goes against mdoc(7), and after I gave a talk about it and posted on arch@, I updated all of our style guides to be consistent and not do this anymore. I'm going through and fixing all the manuals too and have like 260 left. Also Cd takes the rest of the line as an argument here, so the quotes will just confuse people.
57–70	If you put this in a HARDWARE section I can pull it into the release hardware compatibility list automatically. I wrote a style guide in style.mdoc(7). Also, No paragraph break at the end of the a section.
72	No punctuation here, the linter will complain
79	You know... doc makes the code usable. you can put yourself here.

This revision now requires changes to proceed.Sun, Sep 6, 8:10 PM

ngie added inline comments.Sun, Sep 6, 9:25 PM

share/man/man4/apple_bce.4
34–47	We did the prose in SYNOPSIS thing for a while but it's really inconsistent with what SYNOPSIS means in every other section, and it goes against mdoc(7), and after I gave a talk about it and posted on arch@, I updated all of our style guides to be consistent and not do this anymore. I'm going through and fixing all the manuals too and have like 260 left. Also Cd takes the rest of the line as an argument here, so the quotes will just confuse people. Ah, k. I think the loader.conf(5) reference actually has some value BTW (but it can be omitted in the simple case). Sometimes drivers have different names between the module and the driver so noting what the variable is that controls loading the kmod can be really helpful.
57–70	If you put this in a HARDWARE section I can pull it into the release hardware compatibility list automatically. I wrote a style guide in style.mdoc(7). Also, No paragraph break at the end of the a section. I think I deleted the .Sh by accident. Thanks for the catch :).
72	Yeah. There used to be more .Xr . `make manlint` would have definitely uncovered that :).

ngie added inline comments.Sun, Sep 6, 9:26 PM

share/man/man4/apple_bce.4
79	You know... doc makes the code usable. you can put yourself here. I should distinguish @seuros as the driver writer and myself as the manpage writer :).