Page MenuHomeFreeBSD

bhnd: add/update inline documentation comments and man pages
ClosedPublic

Authored by landonf on Nov 9 2017, 7:29 PM.
Tags
None
Referenced Files
Unknown Object (File)
Dec 20 2023, 9:51 PM
Unknown Object (File)
Dec 2 2023, 12:41 PM
Unknown Object (File)
Dec 2 2023, 12:41 PM
Unknown Object (File)
Dec 2 2023, 12:41 PM
Unknown Object (File)
Nov 20 2023, 4:49 AM
Unknown Object (File)
Nov 14 2023, 2:30 PM
Unknown Object (File)
Nov 12 2023, 8:51 PM
Unknown Object (File)
Nov 10 2023, 3:56 AM
Subscribers

Details

Summary

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

Lint
Lint Passed
Unit
No Test Coverage
Build Status
Buildable 12604
Build 12878: arc lint + arc unit

Event Timeline

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.

Fix all igor(1) warnings.

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

In the future, please use full context in review diffs: https://wiki.freebsd.org/action/show/Phabricator?action=show&redirect=CodeReview#Create_a_Revision_via_Web_Interface

Thank you for your work on this.

share/man/man4/bhnd_chipc.4
37
share/man/man4/bhnd_pmu.4
70
ported to
.Fx
and
share/man/man4/bhndb.4
59
To enable use for PCI/PCIe systems, see the
.Xr bhndb_pci 4
driver.
share/man/man4/bhndb_pci.4
38
share/man/man9/bhnd_erom.9
201

s/will be/is/

205

Possessive is probably unnecessary. In general, avoid possessives.

A pointer to a bus I/O instance mapping the first hardware core device
208

Remove \(em.

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

234

This is confusingly worded.

.Dv NULL
is returned if there are no successful probe results from the erom class.
259

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

262

And another.

271

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.

275

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

326

s/will be/is/

328

s/will be/is/

330

s/will be/is/

334

Be imperative.

If the core information is not desired, set
.Fa core
to
353

s/the following/these/

433

Split sentences.

A return value equal to or less than zero indicates success.
Values greater than zero indicate an error and the error code.
439

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

.Er ENXIO
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.

share/man/man9/bhnd_erom.9
208

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?

234

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:

.Dv NULL
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,
share/man/man9/bhnd_erom.9
208

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.

232

s/will be/is/

234

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

If there are no successful probe results from the erom classes,
.Dv NULL
is returned.
259

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 ...an 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 marked 25 inline comments as done.

Applied requested copy and line edits.

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.