Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
To:     Paul Eggert <eggert@cs.ucla.edu>
Cc:     mtk.manpages@gmail.com, linux-man@vger.kernel.org,
        libc-alpha@sourceware.org, gcc@gcc.gnu.org,
        "linux-kernel@vger.kernel.org" <linux-kernel@vger.kernel.org>
References: <41affebd-3354-9420-0048-bffd14535e95@gmail.com>
 <20201001154946.104626-2-colomar.6.4.3@gmail.com>
 <538b683f-01d2-6148-4f1d-1b293eb5cd6b@cs.ucla.edu>
From:   Alejandro Colomar <colomar.6.4.3@gmail.com>
Message-ID: <4b86f6e9-0d8a-f14a-73ce-ebbdc9d9edba@gmail.com>
Date:   Fri, 2 Oct 2020 10:24:39 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101
 Thunderbird/68.12.0
MIME-Version: 1.0
In-Reply-To: <538b683f-01d2-6148-4f1d-1b293eb5cd6b@cs.ucla.edu>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

Hi Paul,

On 2020-10-01 19:32, Paul Eggert wrote:
 > If you're going to document this at all, I suggest documenting 'void' as
 > well as 'void *', and putting both sets of documentation into the same
 > man page.
 >

All the types we're documenting are in the same page:
system_data_types(7).
And then we have links with the name of each type.

And yes, I also pretend to document 'void'.


 > For 'void *' you should also mention that one cannot use arithmetic on
 > void * pointers, so they're special in that way too.

Good suggestion!

 > Also, you should
 > warn that because one can convert from any pointer type to void * and
 > then to any other pointer type, it's a deliberate hole in C's
 > type-checking.

Also good.  I'll talk about generic function parameters for this.

 > It might not also hurt to mention 'void const *', 'void
 > volatile *', 'void const volatile *', etc.

Those are qualifiers for the type,
and I don't see how any of them would apply differently to 'void *'
than to any other pointer type (or any type at all),
so I think they don't belong to system_data_types(7).

However, it might be good that someone starts a page called
'type_qualifiers(7)' or something like that.

I would love that someone documents 'volatile' correctly,
as there aren't many good sources about it.
If someone who knows when to use --and especially when not to use--
'volatile', is reading this, think about it :-)
I still wonder if I used it correctly in the few cases I've had to.

BTW, I'll CC the LKML.

 >
 > For 'void' you can mention the usual things, such as functions returning
 > void, and functions declared with (void) parameters, why one would want
 > to cast to (void), and so forth.

Yes, I was thinking about that.

 >
 > You're starting to document the C language here, and if you're going to
 > do that you might as well do it right.

I'm trying to do so :)

Thanks,

Alex