Improve the clarity and readability of device.hints.5.
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Skipped - Unit
Tests Skipped
Event Timeline
| share/man/man5/device.hints.5 | ||
|---|---|---|
| 69–71 | I'd say: "ISA or system on chip device drivers" | |
| 89 | I'm skeptical of the value of this list unless we're going to make a pass through the manpages for all the keywords currently in use. In general, the set accepted by a given driver are documented in the driver manpage. | |
| 111–112 | resource_int_value.9 is an internal detail and seems out of place here. | |
| share/man/man5/device.hints.5 | ||
|---|---|---|
| 89 | 'flags' 'at' and 'disabled' at least, are used inside of subr_bus.c While I share the skepticism, some simple wording may help. Many of these things like IRQ and DRQ are up to the bus to configure, not the driver. And the ISA bus at that. But this is by far our biggest use of hints, so it seems reasonable to include carefully worded messages here. | |
Comment Actions
Looks good as is. A bit more word smithing around the keywords wouldn't hurt, but I'm ok with what's there now.
| share/man/man5/device.hints.5 | ||
|---|---|---|
| 89 | I'm fine with leaving this alone. My main issue is that while it does tell you what the standard values mean, that's not very useful to the reader since they can't know which ones (other than 'flags' 'at' and 'disabled') even apply to their device. Directing users to consult the manpage for their device for supported flags is likely one more helpful. | |
| share/man/man5/device.hints.5 | ||
|---|---|---|
| 89 | What if we change the introduction to the table on line 86 from saying "The keyword may be:" to "Typical keywords include:"? | |
| share/man/man5/device.hints.5 | ||
|---|---|---|
| 89 | Works for me. | |
Comment Actions
Change "The keyword may be:" to "Typical keywords include:" to show that the list is not exhaustive.