Page MenuHomeFreeBSD
Differential D51240

snd_uaudio.4: Rework SYNOPSIS, add HARDWARE, SPDX
ClosedPublic
Actions

Authored by ziaee on Jul 10 2025, 11:21 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sun, Oct 12, 1:21 AM
Unknown Object (File)
Sun, Oct 12, 1:21 AM
Unknown Object (File)
Sun, Oct 12, 1:21 AM
Unknown Object (File)
Sun, Oct 12, 1:21 AM
Unknown Object (File)
Sun, Oct 12, 1:21 AM
Unknown Object (File)
Sun, Oct 12, 1:20 AM
Unknown Object (File)
Sat, Oct 11, 3:50 PM
Unknown Object (File)
Wed, Oct 8, 4:39 AM
View All 50 Files
Subscribers
danfe
imp
pauamma_gundo.com

Details

Reviewers
christos
Group Reviewers
manpages
Commits
rG701072154af0: snd_uaudio.4: Rework SYNOPSIS, add HARDWARE, SPDX
Summary

+ Rework synopsis for consistency
+ Add a HARDWARE section for HW relnotes
+ tag SPDX

MFC after: 3 days

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

ziaee created this revision.Jul 10 2025, 11:21 PM
Herald added a subscriber: imp. · View Herald TranscriptJul 10 2025, 11:21 PM
ziaee requested review of this revision.Jul 10 2025, 11:21 PM
Harbormaster completed remote builds in B65327: Diff 158291.Jul 10 2025, 11:21 PM
ziaee added inline comments.Jul 10 2025, 11:22 PM
share/man/man4/snd_uaudio.4
52

I try to put a sensible non-default option here, but I didn't know what to put for this one.

ziaee mentioned this in D51262: HW Relnotes: Move uaudio to Sound.Jul 11 2025, 5:44 PM
christos added inline comments.Jul 13 2025, 3:06 PM
share/man/man4/snd_uaudio.4
54

Is it advised to write sysctls like this in the synopsis?

72

This is a duplicate of the first paragraph in the DESCRIPTION section. We should keep one of them.

ziaee added inline comments.Jul 13 2025, 4:24 PM
share/man/man4/snd_uaudio.4
54

As kernel declarations? Yes, they universally take this form when in synopsis. I should clarify this in style.mdoc(7).

72

Understood. We need this one for HW Relnotes, so I will remove the former in next update.

christos added inline comments.Jul 13 2025, 4:28 PM
share/man/man4/snd_uaudio.4
72

Is there a reason you don't (re)move it here?

ziaee added inline comments.Jul 13 2025, 5:35 PM
share/man/man4/snd_uaudio.4
72

Sorry, I meant the next update to this patch. The reason I didn't initially is because I think it is a very sane introductory sentence.

christos added inline comments.Jul 13 2025, 6:29 PM
share/man/man4/snd_uaudio.4
72

I think it's a bit weird to include the exact same sentence twice. After all the man page is short so it's fine to just leave this only in HARDWARE.

ziaee updated this revision to Diff 158485.Jul 14 2025, 4:38 PM

Remove duplicate text from introductory sentence, thanks.

I still need some advice on the unset value in SYNOPSIS?

Harbormaster completed remote builds in B65427: Diff 158485.Jul 14 2025, 4:38 PM
christos added a comment.Jul 15 2025, 1:14 PM

I am actually not sure why we need to show default values in the SYNOPSIS section. As is explained in SYSCTL VARIABLES, sometimes a value of 0 has special meaning. I am actually not sure of the advantage of including those in the SYNOPSIS in the first place, since we enumerate right below almost. But if we are to list them, I do not think we should provide values as well.

share/man/man4/snd_uaudio.4
51
ziaee updated this revision to Diff 158675.Jul 17 2025, 4:00 PM
ziaee marked 5 inline comments as done.

That sounds good. You're right, utilities don't list valid arguments
to their options in SYNOPSIS, they just list them!

Harbormaster completed remote builds in B65522: Diff 158675.Jul 17 2025, 4:00 PM
christos added a comment.Jul 17 2025, 4:38 PM

Please note that snd_uaudio(4) can also create some sysctls under dev.pcm.*, that is, dev.pcm.%d.mixer (along with sub-sysctls) and dev.pcm.%d.feedback_rate. The former is documented in BUGS (for some reason), and the latter is not documented at all.

share/man/man4/snd_uaudio.4
39

Don't we need this anymore?

51
ziaee updated this revision to Diff 158685.Jul 17 2025, 5:33 PM

s/channel/channels/, thanks!

Harbormaster completed remote builds in B65527: Diff 158685.Jul 17 2025, 5:33 PM
ziaee added inline comments.Jul 17 2025, 5:33 PM
share/man/man4/snd_uaudio.4
39

In the beginning we didn't, and then somewhere along the way we started to. I think it's a violation of consistency in mdoc(7). SYNOPSIS shows you the options, unless it's section 4 then it's a description in prose. In the other sections of the manual, SYNOPSIS all means the same thing, and it makes it predictable. I've been trying to fix this so it provides the same thing in section 4. Descriptions on usage should be in DESCRIPTION. I gave a lighting talk about it at BSDCan:

https://people.freebsd.org/~ziaee/tmp/bsdcan25lightning-ziaee.webm

christos accepted this revision.Jul 17 2025, 6:47 PM

LGTM, but I think we should also document the dev.pcm.* controls I mentioned in my last comment.

This revision is now accepted and ready to land.Jul 17 2025, 6:47 PM
pauamma_gundo.com added a subscriber: pauamma_gundo.com.Jul 17 2025, 7:15 PM

Other than bumping Dd (and maybe adding the missing sysctls), LGTM.

share/man/man4/snd_uaudio.4
33

Remember to bump.

ziaee added a comment.Jul 17 2025, 7:46 PM

Thanks so much for your attention to this matter. I'm going to add them in an immediate followup review!

Closed by commit rG701072154af0: snd_uaudio.4: Rework SYNOPSIS, add HARDWARE, SPDX (authored by ziaee). · Explain WhyJul 17 2025, 7:56 PM
This revision was automatically updated to reflect the committed changes.
ziaee added a commit: rG701072154af0: snd_uaudio.4: Rework SYNOPSIS, add HARDWARE, SPDX.
danfe added a subscriber: danfe.Jul 18 2025, 4:35 AM

I gave a lighting talk about it at BSDCan

Thanks for sharing, haven't seen this video clip before. I fully agree and like the useful, concise mtw(4) example, please keep it up!

Revision Contents
Changeset List

PathSize
share/
man/
man4/
36 lines

Diff 158702

View Options

share/man/man4/snd_uaudio.4

Loading...