Re: [PATCH] NULL.3def: Add documentation for NULL

[Ralph Corderoy <ralph@inputplus.co.uk>]

Hi Alejandro,

> As hinted in recent mails to groff@ and linux-man@,
> I'm going to inaugurate a new [sub]section for constants.

This seems a bad idea.  They're quite at home in section 3.

> I think it should contain constants, normally represented by
> object-like macros in C.  But it should also contain other forms of
> constants in other languages (e.g., C++'s constexpr variables), so I'm
> not convinced by the name 3def.

3const was seem more in line with how you keep referring to it.

> I'm (very) tempted to inaugurate section 11 for this

That's seems a worse idea.  They're far too trivial to deserve their own
section.

> The initial page for this section is non other than NULL ;)

It seems a bit simple to be worthy of its own man page.

> +.TH NULL 3def 2022-07-22 Linux "Linux Programmer's Manual"
> +.SH NAME
> +NULL \- null pointer constant

It's one of them.  An integer constant expression with the value 0 is
also a null pointer constant.

> +.SH SYNOPSIS
> +.nf
> +.B "#define NULL  ((void *) 0)"

Does the reader need to know the definition of a macro?
Are you intending to do this for all macros and constants?

> +A null pointer is one that doesn't point to a valid object.

...or function.

> +When it is necessary to set a pointer variable to a null pointer,
> +it is not enough to use
> +.IR "memset(&p, 0, sizeof(p))" ,
> +since ISO C and POSIX don't guarantee that a bit pattern of all
> +.BR 0 s
> +would represent a null pointer.

‘p = 0’ would suffice there; it may be better to give the typical case
where the pointer is part of a struct.

Also, sizeof is an operator, not a function as the parenthesis and lack
of space suggest.  ‘memset(&p, 0, sizeof p)’ is clearer.  Perhaps you're
following some house style.

> +.SH SEE ALSO
> +.BR memset (3),
> +.BR void (3type)

More importantly, see also stddef.h(0p), as the man page hasn't yet told
me how to obtain NULL's definition.  Am I to copy the definition into my
code?

POSIX has a man page per standard header; that seems a good level to
cover all the little things which each header file is defined to
provide.  If you really want to create work, consider a man page which
tables NULL, EOF, etc., and the header-file man-page to read.

-- 
Cheers, Ralph.