Hi Paul,

On 2026-02-24T15:19:14-0800, Paul Eggert wrote:
> On 2026-02-24 15:05, Alejandro Colomar wrote:
> > > > 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);

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?

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