Alejandro Colomar wrote:

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.

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.



 - Mark

Have a lovely day!
Alex

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