Re: [PATCH v4] NULL.3const: Add documentation for NULL

[Alejandro Colomar]

Hi Branden,

On 7/26/22 17:54, G. Branden Robinson wrote:
> [...relocated material for a topic shift...]
>
> > +.SH NOTES
> > +The following headers also provide
> > +.BR NULL :
> > +.IR <locale.h> ,
> > +.IR <stdio.h> ,
> > +.IR <stdlib.h> ,
> > +.IR <string.h> ,
> > +.IR <time.h> ,
> > +.IR <unistd.h> ,
> > +and
> > +.IR <wchar.h> .
>
> Not exactly on topic (sorry), but apropos of our concurrent discussion
> on man pages for constants with external linkage and data types, the
> foregoing is an excellent counterexample of what I contend is good
> practice: document them in the man page for the header file.

For countering that, I'd point you to tm(3type).
If I document in such detail every type and constant in <time.h>, the 
page will become an unreadable mess, IMO.

NULL(3const) is also a good example.  stddef(0posix) has 2 lines + a 
blank for NULL.

Now consider a page that documents NULL, offsetof(), ptrdiff_t, size_t 
(all of them already documented, so you can take a look at their pages 
to get an idea of their docs), + wchar_t (yet undocumented).

stddef.h(0posix) is very short about them, and IMO, it's quite 
incomplete.  But I could live with it if I had link pages to it (it 
would be suboptimal to my needs, but I could certainly live with it).





> It is only the standard C library that avails itself of such a rampant
> multiplicity of definition sites for constants.  This is of course
> because of the synergy of 2 factors: (1) the library header design is
> modular, and yet (2) the null pointer is ubiquitous and supports
> applications in many application areas.
>
> To me, this supports rather than undermines my argument for header file
> man page contents, because as we can see here, what we've diagnosed is
> really a missed opportunity to define the null pointer constant _at the
> language level_ instead of relegating it to an optional feature of the
> standard library which you nevertheless will have a hard time doing
> without.  C programmers can code freestanding applications without
> resource to the standard C library.  What are these freestanding
> applications, invariably?  Operating system kernels, or machine-mode
> code doing the work of an OS alongside its (presumably embedded,
> microcontroller-like) function.  Are _those_ going to have a use for a
> null pointer constant?  What do you think?  ;-)

What do I think?

Many blame C and Unix/Linux development because of how they've grown:
each vendor added their extensions to a "common" idea of the language 
and the system, often with incompatible extensions.  Resulting in a huge 
mess, very inconsistent, and suboptimal.

I think that's the best that could possibly have happened.  A sort of 
natural selection.  I don't believe the idea that the gods K & R et al. 
brought us a god language and system and we humans broke it.  Yes, the 
original language and system were good, but far from what they are now.

Then, other languages and systems have seen a more strict development, 
where the design was more centralized (or at least "better" thought).  I 
can only say that I don't like them as much.

Yes, half a century after the invention of C we now kind of agree on 
things like NULL could be part of the language.  But now it's maybe too 
late for that.  And really, who cares?  gcc implements it as if it were 
part of the language: <stddef.h> doesn't even exist.  You could probably 
suggest making NULL a language keyword for the next revision of the 
standard, but I don't think it will get much attention.  But maybe it 
would be a good thing...

> POSIX supplements to the standard C library, and other libraries for C,
> will not typically have this difficulty, and will have one definition
> site only for their constants with external linkage.

Oh, no.  Check ssize_t(3type)!

Cheers,

Alex

--
Alejandro Colomar
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature