bhnd: add/update inline documentation comments and man pages

Authored by landonf on Nov 9 2017, 7:29 PM.



This includes a number of copyedits for the inline code documentation comments, updates to the existing bhnd(4), bhndb(4), bcma(4), and siba(4) man pages, and new man pages for bhnd_chipc(4), bhnd_pmu(4), bhndb_pci(4), bhnd(9), and bhnd_erom(9).

The bhnd(9) and bhnd_erom(9) man pages were automatically generated by parsing the inline code comments, and then hand-edited to bring them into sync with standard man page conventions and groff_mdoc(9).

Depends on D12708, D12664, D12518, D12385, D12582

Test Plan

I've posted PDF rendered versions of bhnd(9) and bhnd_erom(9) for easier proofing:

Diff Detail

rS FreeBSD src repository
Automatic diff as part of commit; lint not applicable.
Automatic diff as part of commit; unit tests not applicable.
landonf created this revision.Nov 9 2017, 7:29 PM
landonf retitled this revision from bhnd: Update inline documentation comments, and add/update man page documentation for bhnd(4), bcma(4), siba(4), bhnd_chipc(4), bhnd_pmu(4), bhndb(4), bhndb_pci(4), bhnd(9), and bhnd_erom(9). to bhnd: add/update inline documentation comments and man pages.Nov 9 2017, 7:33 PM
landonf added a reviewer: manpages.
landonf updated this revision to Diff 35013.Nov 9 2017, 8:10 PM

Fix all igor(1) warnings.

landonf updated this revision to Diff 35014.Nov 9 2017, 8:15 PM

regenerated diff with git's incorrect rename tracking heuristics disabled.

wblock added a subscriber: wblock.Nov 17 2017, 6:41 PM

In the future, please use full context in review diffs:

Thank you for your work on this.

37 ↗(On Diff #35014)
70 ↗(On Diff #35014)
ported to
59 ↗(On Diff #35014)
To enable use for PCI/PCIe systems, see the
.Xr bhndb_pci 4
38 ↗(On Diff #35014)
200 ↗(On Diff #35014)

s/will be/is/

204 ↗(On Diff #35014)

Possessive is probably unnecessary. In general, avoid possessives.

A pointer to a bus I/O instance mapping the first hardware core device
207 ↗(On Diff #35014)

Remove \(em.

"Should be mapped" implies that it is not required. If it is required, this would be "must be mapped".

233 ↗(On Diff #35014)

This is confusingly worded.

is returned if there are no successful probe results from the erom class.
258 ↗(On Diff #35014)

There is another \(em, which I suspect is from either an editor or a well-meaning but misguided man page generator.

261 ↗(On Diff #35014)

And another.

270 ↗(On Diff #35014)

Avoid possessives. They get ugly easily, and few people in the post-literacy world understand them precisely. In this case, it is not even needed, just remove the apostrophe.

274 ↗(On Diff #35014)

"may" implies permission. "can" is probably a better word here.

325 ↗(On Diff #35014)

s/will be/is/

327 ↗(On Diff #35014)

s/will be/is/

329 ↗(On Diff #35014)

s/will be/is/

333 ↗(On Diff #35014)

Be imperative.

If the core information is not desired, set
.Fa core
352 ↗(On Diff #35014)

s/the following/these/

432 ↗(On Diff #35014)

Split sentences.

A return value equal to or less than zero indicates success.
Values greater than zero indicate an error and the error code.
438 ↗(On Diff #35014)

"should be"? This sounds like sometimes it might not be.

is returned if the device is not supported by the parser.

Thanks for reviewing; I've inlined a couple questions, and I'll follow up in a bit with the remaining requested edits.

207 ↗(On Diff #35014)

I can replace the em dash here by breaking this into two sentences, but what should I be using in other locations where a pair of commas is insufficient?

233 ↗(On Diff #35014)

Since this is plural (if _any_ erom class succeeds, the call succeeds; if _all_ erom classes fail, the call fails), this would have to be:

is returned if there are no successful probe results from an erom class.

I'm not sure that's actually less confusing :-)

Perhaps this?

If none of the probed erom classes return a successful probe result,
wblock added inline comments.Nov 18 2017, 5:04 PM
207 ↗(On Diff #35014)

In general, two short declarative sentences are preferable to an emdash. The uses here are kind of asides, which again are better as two separate sentences.

231 ↗(On Diff #35014)

s/will be/is/

233 ↗(On Diff #35014)

Some redundancy with "returns" and "probe". Hmm, maybe:

If there are no successful probe results from the erom classes,
is returned.
258 ↗(On Diff #35014)

This is an "aside". Typically, they use parentheses, but are better moved to a later sentence to avoid interrupting the train of thought of the reader.

This is attempt. It's still early here, so apologies for probably weak wording.

Clients can manage the allocation of memory themselves with
.Fn bhnd_erom_init_static .
This is useful in cases like performing device enumeration before
.Xr malloc 9
has been initialized.
.Fn bhnd_erom_init_static
is called with 
.Fa erom
set to a pointer to the memory for the instance and
the total available bytes in
​.Fa esize .
landonf updated this revision to Diff 35559.Nov 21 2017, 7:18 PM
landonf marked 25 inline comments as done.

Applied requested copy and line edits.

adrian accepted this revision.Nov 27 2017, 8:03 PM
This revision is now accepted and ready to land.Nov 27 2017, 8:03 PM
This revision was automatically updated to reflect the committed changes.