Page MenuHomeFreeBSD

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

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

Details

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

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.

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.

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.

share/man/man4/snd_uaudio.4
72

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

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.

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.

Remove duplicate text from introductory sentence, thanks.

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

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 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!

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

s/channel/channels/, thanks!

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

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

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

share/man/man4/snd_uaudio.4
33

Remember to bump.

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

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!