This new manpage describes what the apple_bce driver services, how the
driver is configured, and what Apple models the driver claims to
support.
Details
Details
Diff Detail
Diff Detail
- Repository
- rG FreeBSD src repository
- Lint
Lint Skipped - Unit
Tests Skipped - Build Status
Buildable 76613 Build 73496: arc lint + arc unit
Event Timeline
Comment Actions
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... | |
| share/man/man4/apple_bce.4 | ||
|---|---|---|
| 34–47 |
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 |
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 :). | |
| share/man/man4/apple_bce.4 | ||
|---|---|---|
| 72 |
I added usb(4) to the SEE ALSO list :). | |
| share/man/man4/apple_bce.4 | ||
|---|---|---|
| 38 | Branding nit. | |
Comment Actions
LGTM after moving the HARDWARE section heading up a bit. Thanks ngie!
| share/man/man4/apple_bce.4 | ||
|---|---|---|
| 31 | Line 30 should be moved after line 24, and the paragraph break (Pp) should be deleted. | |
| 34–47 |
+1 | |
| share/man/man4/apple_bce.4 | ||
|---|---|---|
| 31 |
*looks at rendered output -> 🤦* Yes... putting HARDWARE there looks really silly. Haha. | |
| share/man/man4/apple_bce.4 | ||
|---|---|---|
| 54 | This is a new pattern here. Normally the code Authors are here. The man copyright are who wrote it. It just a nit, but this driver is not fully complete, so we still have to edit it once i push the extra handlers. | |
| share/man/man4/Makefile | ||
|---|---|---|
| 974–975 | why put this here? 30 lines up theres already an amd64 block. the synopsis says it needs usb, so I'd think we'd want the logic in the block around line 1097? | |
| share/man/man4/apple_bce.4 | ||
| 31 | It'd be even better in the hardware release note, just a random few bullet points listing some computers :P | |
| 54 |
Not remotely, although the listing of authors without prose is more traditional (and I do prefer that), it does not distinguish between who wrote the .c, the .h, or the .8. Also, I disagree with the underlying premise that they are at all separate. The docs and code are both absolutely integral parts of a useful software. $ cd src/share/man/man4/; git grep "written by" | grep man | wc -l 272 | |