Re: [PATCH] man/: SYNOPSIS: Remove GNU forward-declarations of parameters for lengths of array parameters

[Alejandro Colomar <alx+linux-man@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 1986 bytes --]

Hi Mark,

> Date: 2026-10-22 15:03:37-0700
> From: Mark Harris <mark.hsj@gmail.com>
>
[...]
> 
> The man pages are frequently used when seeing a call to an unfamiliar
> function, to understand what the function expects and what it is doing
> with those arguments.  The arguments in the call are matched to the
> synopsis by order, not by name, so for example a person questioning
> the first argument would naturally be looking at the first thing after
> the "(" to find out what is expected there.
>
> A person that is reading the description, where it refers to the
> arguments by name, needs to convert that name to the argument number
> in order to match it to the arguments in the actual call.  The natural
> way to do that is to count the argument names in the synopsis (at
> least those not preceded by an unterminated bracket or comment) and
> stop when that name is found.  For example if that is the first
> argument name after the "(" in the synopsis then it would be natural
> to conclude that it matches the first argument to the call, and not
> continue scanning to see if there is another occurrence of the same
> argument name.

That's a valid concern, but most often the first argument will be of
a different and incompatible type (they tend to be pointers, which is
the reason we need the forward declaration in the first place), and thus
such a mistake in the understanding of the order of arguments will
result in a compiler error, which is a relatively mild problem.

You didn't take into account my other concerns, though.  I'd like to
hear your opinion about the concerns that letting users think that is
valid C might lead to them writing code that has UB (or logic errors).

> So I agree with Michael that this change is a good one to make the man
> pages less confusing.  Thanks for creating the change.

Thanks for your feedback!

> 
>  - Mark


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]