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

[Ingo Schwarze <schwarze@usta.de>]

Hi,

Alejandro Colomar wrote on Tue, Jul 26, 2022 at 08:47:59PM +0200:
> On 7/26/22 17:54, G. Branden Robinson wrote:
>> Alejandro Colomar wrote:

>>> +.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).

For once, i agree.  Manual pages for header files (like stddef.h(3))
are an even worse idea than manual pages for preprocessor constants
and data types.  The main reason is that almost every header file
includes so much material that such pages would become unreasonably
large, just as Alejandro explains above.  Besides, the material in
a typical header file is not so closely related among itself that
it should share a manual page.  And in fact, documentation for
almost every header file is already split up into many manual
pages: one for each group of closely related functions.

[...]
>> 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)!

Indeed.

Then again, while NULL and size_t are exceptional in so far as they
are so widely used that there is no clear place for documenting them,
most types are better documented together with the most typical
function using them.

For example, document  struct tm  in  localtime(3)  and
                       ssize_t    in  read(2).

Besides, almost nothing needs to be said where ssize_t is documented.
In particular, documentation of %zd belongs with printf(3), not with
ssize_t(3type).

Yours,
  Ingo