man9: Add a manual page for kstack_contains(9).
ClosedPublic
Actions

Authored by jkoshy on May 2 2023, 9:39 AM.

Details

Reviewers

gnn
mhorne

Commits

rGc2eae5c39adc: man9: Add a manual page for kstack_contains(9).

Summary

man9: Add a manual page for kstack_contains(9).

Diff Detail

Repository

rG FreeBSD src repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

jkoshy created this revision.May 2 2023, 9:39 AM

Herald added a subscriber: imp. · View Herald TranscriptMay 2 2023, 9:39 AM

jkoshy requested review of this revision.May 2 2023, 9:39 AM

Harbormaster completed remote builds in B51306: Diff 121374.May 2 2023, 9:39 AM

jkoshy added a reviewer: mhorne.May 2 2023, 9:44 AM

Thanks! This is a very welcome addition.

share/man/man9/kstack_contains.9
28	`mandoc -Tlint` prefers this.
35	.In machine/stack.h
39–40	(it is all threads not just kernel threads)
45
48–50	.Fa for function arguments.
56

Addressed review comments.

Harbormaster completed remote builds in B51308: Diff 121385.May 2 2023, 2:33 PM

Addressed review comments.

LGTM, with one more nit that can be fixed before commit.

One thing I am trying to be more considerate of when it comes to section 9 pages is "how can this page be discovered?" In other words, is it cross-referenced from another man page or is it referenced anywhere in the source code? I do not think there are any obvious candidates which should reference kstack_contains(9) in their SEE ALSO, but pointing to the man page at the kstack_contains() definitions might help the reader learn that the page exists at all. Just something to consider, I am not asking you to do anything specific here.

share/man/man9/kstack_contains.9
55	Sorry, one more that I missed.

This revision is now accepted and ready to land.May 2 2023, 3:29 PM

Address a review comment.

This revision now requires review to proceed.May 2 2023, 5:37 PM

Addressed a review comment.

Harbormaster completed remote builds in B51316: Diff 121403.May 2 2023, 5:38 PM

mhorne accepted this revision.May 2 2023, 5:55 PM

This revision is now accepted and ready to land.May 2 2023, 5:55 PM

One thing I am trying to be more considerate of when it comes to section 9
pages is "how can this page be discovered?" In other words, is it cross-referenced
from another man page or is it referenced anywhere in the source code? I do not
think there are any obvious candidates which should reference kstack_contains(9)
in their SEE ALSO, but pointing to the man page at the kstack_contains() definitions
might help the reader learn that the page exists at all. Just something to consider,
I am not asking you to do anything specific here.

My guess is that readers are likely to run man 9 kstack_contains when they
come across it in the source code, so it would be implicitly discoverable.

Should we re-purpose intro(9) to mention the major groups of section 9 APIs?

In D39933#909021, @jkoshy wrote:

Should we re-purpose intro(9) to mention the major groups of section 9 APIs?

This is actually exactly my plan, and I have a rewrite of this page in-progress. I definitely want to have that completed for the 14.0 release, so you can expect to see a review in the next couple of weeks.

Approved

Closed by commit rGc2eae5c39adc: man9: Add a manual page for kstack_contains(9). (authored by jkoshy). · Explain WhyMay 5 2023, 2:44 PM

This revision was automatically updated to reflect the committed changes.

jkoshy added a commit: rGc2eae5c39adc: man9: Add a manual page for kstack_contains(9)..