Re: Unused GCC builtins

[Martin Sebor <msebor@gmail.com>]

On 01/24/2018 07:09 AM, Jakub Jelinek wrote:
> On Wed, Jan 24, 2018 at 03:04:55PM +0100, Manuel Rigger wrote:
>> In a second step, we also considered internal builtins and found that the
>> vararg handling builtins (__builtin_va_start, __builtin_va_end,
>> __builtin_va_arg, and __builtin_va_copy) are relied upon by many projects,
>> even though they are undocumented in GCC's builtins API. Could they be
>> added to the documentation?
>
> Why?  What is documented is va_start/va_end/va_arg/va_copy, that is
> what people should use, the builtins are just internal implementation of
> those macros.

There are a number of reasons why documenting visible APIs is
helpful whether or not they are meant to be used by end users.

Features that are not meant to be used should be documented
as such.  Mentioning that they are meant only for internal use
makes their purpose clear and sets the right expectation about
the level of support and portability between GCC versions.  It
also makes it clear that we didn't forget to document them by
accident.

The manual isn't just a reference for GCC users.  It's also
a helpful reference for developers of GCC-compatible compilers
who are not allowed to read GCC source code due to copyright or
licensing constraints, or for people maintaining or supporting
their own GCC-based operating environments.  Finally, it is also
a reference for GCC developers.

For all these reasons I think every built-in that can be used
(intentionally or otherwise) deserves to be documented in
the manual.

Martin