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
