Hi Mark,

On Sat, Jun 28, 2025 at 04:38:31PM -0700, Mark Harris wrote:

Alejandro Colomar wrote:

quoted

Hi Mark & Mark,

On Fri, Jun 06, 2025 at 03:05:20PM +0200, Alejandro Colomar wrote:

quoted

I'm not going to release these changes soon, though.  They cause some
minor temporary regressions, so I'm considering when I should do it.
But eventually, these changes will be released.

I found a way to do this without a regression.  I've pushed the change
already to master.  Please check that you like the pages now.  I find
them much nicer.  I'll try to have a release soon.

This does look better than the bolded forward declarations; thanks for
doing this.

You're welcome!

Honestly, though, I think it would be even better without the forward
declarations at all, which are just repeating information that is
already present shortly afterwards.  It may not follow the proposed C
declaration syntax, but the Synopsis section already does not match
what you would write in C.  That is, you wouldn't write:

       #include <stdio.h>

       size_t fread(size_t size, size_t n;
                    void ptr[restrict size * n],
                    size_t size, size_t n,
                    FILE *restrict stream);

as stated in the Synopsis section.  Not only is an array of void
invalid, but at best that would declare the function twice.

What the reader needs to know is how to call the function, not how to
declare it.  In fact, users are discouraged from declaring the
function, which is already taken care of by the header file.  It's
just that the C function call syntax doesn't include the types, so the
types are added using the same syntax that is used in declarations,
even though the reader has no need for another function declaration.
The syntax without the forward declarations is closer to the function
call syntax that is needed, while also providing the necessary type
information.

I've had people complain in the opposite direction too, so I guess we
can say the current way is a compromise that works for both.

About arrays of void, I'm not as worried as I'd be if we used the
parameters without a forward declaration.  If programmers try to declare
their functions using arrays of void, their compiler will tell them they
can't.  However, if someone tries the same thing with undeclared
parameters, it might "work", which would be rather dangerous.

So, I'll keep the standard syntax in that regard.


Have a lovely day!
Alex

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