Re: [PATCH] extend.texi: Fix up defbuiltin* with spaces in return type

[Sandra Loosemore <sandra.loosemore@siemens.com>]

On 12/1/23 10:33, Jakub Jelinek wrote:
> On Fri, Dec 01, 2023 at 10:04:38AM -0700, Sandra Loosemore wrote:
>> Thanks, this looks good to me.  I think I also noticed this weird formatting
>> in passing recently when I was looking for something else and did not have
>> time to track it down myself.
> 
> There is another question.  In many cases we just specify types for the
> builtin arguments, in other cases types and names with @var{name} syntax,
> and in other case with just name.
> 
> @defbuiltin{int __builtin_fpclassify (int, int, int, int, int, ...)}
> vs.
> @defbuiltin{size_t __builtin_object_size (const void * @var{ptr}, int @var{type})}
> vs.
> @defbuiltinx{bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res)}
> and in some cases even just name the arguments and don't specify type:
> @defbuiltin{void __builtin_clear_padding (@var{ptr})}
> @defbuiltin{@var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2})}
> 
> Shall we tweak that somehow?  If the argument names are unimportant, perhaps
> it is fine to leave that out, but shouldn't we always use @var{...} around
> the parameter names when specified?

Yup.  The Texinfo manual says:  "When using @deftypefn command and variations, 
you should mark parameter names with @var to distinguish these from data type 
names, keywords, and other parts of the literal syntax of the programming 
language."

> And avoid leaving out the types, use something like
> __builtin_clear_padding (@var{type} *@var{ptr})
> or
> __builtin_choose_expr (@var{type1} @var{const_exp}, @var{type2} @var{exp1}, @var{type3} @var{exp2})
> ?

That would probably be good too.

-Sandra