Alejandro Colomar wrote:

Hi Paul,

On 2026-02-24T15:19:14-0800, Paul Eggert wrote:

quoted

On 2026-02-24 15:05, Alejandro Colomar wrote:

quoted

quoted

quoted

How would you document strchr(3)?

I'd do what the standard does rather than reinvent this particular wheel.

So, you'd use QChar?

Yes. As confusing as QChar/QVoid is, it'd likely be more confusing overall
for us to invent our own notation.

Hmmmm, okay.  I see conflicting opinions (others prefer C++-like
overload notation).  I think I prefer QChar/QVoid, but am not convinced
of which to use.

Whichever we use, we need to distinguish cases like strnul(3) from cases
like strchr(3).  I think I'd do it like this:

        strchr(3)
        SYNOPSIS
                #include <string.h>

                QChar *strchr(QChar *s, int c);

                #undef strchr
                char *strchr(const char *s, int c);

I don't see how anyone would understand what this is trying to convey,
unless they were already familiar with the C23 changes to strchr.  The
#undef in the middle makes it worse, because it appears to be going
out of its way to describe the function using strict C syntax, even to
the point of sacrificing normal synopsis conventions and clarity.
However QChar is not a C type or macro, so by making it appear that
the synopsis is supposed to be interpreted strictly as C code it just
ends up making it more confusing.  The C23 style only works if you can
put QChar in italics, as in C23, or some other style that clearly
distinguishes it from a type name or C code.  If you don't like the
two-line synopsis it would be better to just leave the synopsis as it
was, and add a sentence to the description that in C23 a
const-qualified argument propagates the const qualification to the
result type.

 - Mark

The above documents that you can #undef the macro, which provides the
function with the different prototype.  And then strnul(3) would only
have the QChar prototype, as there's no function.

        strnul(3)
        SYNOPSIS
                #include <string.h>

                QChar *strnul(QChar *s);

What do you think?

quoted

Whichever notation we use, we need to
explain the business with void * arguments anyway.

Hmmm, yeah, this and other corner cases lead me to think QChar/QVoid
would be better.  It would allow me to write a manual page describing
those.  And I expect people will eventually get used to that syntax;
it's a matter of time.


Have a lovely night!
Alex

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