extend.texi: Fix up defbuiltin* with spaces in return type
Checks
Commit Message
Hi!
In https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005fstdc_005fbit_005ffloor
I've noticed that while e.g. __builtin_stdc_bit_floor builtin is properly
rendered in bold and bigger size, for the __builtin_stdc_bit_width builtin
it is not the builtin name which is marked like that, but the keyword int
before it. Also, seems such builtins are missing from the index.
I've read the texinfo docs and they seem to suggest in
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Line-Macros.html
that return types of functions with spaces in the return type should be
wrapped with {}s and we already use that e.g. in
@defbuiltin{{void *} __builtin_thread_pointer (void)}
The following patch adjusts builtins I found which contained one or two
spaces in the return type name (plus two spots which used 2 spaces after
single keyword return type instead of 1 which triggered my search regex as
well).
Tested on x86_64-linux, ok for trunk?
2023-12-01 Jakub Jelinek <jakub@redhat.com>
* doc/extend.texi (__builtin_addc, __builtin_addcl, __builtin_addcll,
__builtin_subc, __builtin_subcl, __builtin_subcll,
__builtin_stdc_bit_width, __builtin_stdc_count_ones,
__builtin_stdc_count_zeros, __builtin_stdc_first_leading_one,
__builtin_stdc_first_leading_zero, __builtin_stdc_first_trailing_one,
__builtin_stdc_first_trailing_zero, __builtin_stdc_has_single_bit,
__builtin_stdc_leading_ones, __builtin_stdc_leading_zeros,
__builtin_stdc_trailing_ones, __builtin_stdc_trailing_zeros,
__builtin_nvptx_brev, __builtin_nvptx_brevll, __builtin_darn,
__builtin_darn_raw, __builtin_ia32_vec_ext_v2di,
__builtin_ia32_crc32qi, __builtin_ia32_crc32hi,
__builtin_ia32_crc32si, __builtin_ia32_crc32di): Put {}s around
return type with spaces in it.
(__builtin_rx_mvfachi, __builtin_rx_mvfacmi): Remove superfluous
whitespace.
Jakub
Comments
On 12/1/23 03:26, Jakub Jelinek wrote:
> Hi!
>
> In https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005fstdc_005fbit_005ffloor
> I've noticed that while e.g. __builtin_stdc_bit_floor builtin is properly
> rendered in bold and bigger size, for the __builtin_stdc_bit_width builtin
> it is not the builtin name which is marked like that, but the keyword int
> before it. Also, seems such builtins are missing from the index.
>
> I've read the texinfo docs and they seem to suggest in
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Line-Macros.html
> that return types of functions with spaces in the return type should be
> wrapped with {}s and we already use that e.g. in
> @defbuiltin{{void *} __builtin_thread_pointer (void)}
>
> The following patch adjusts builtins I found which contained one or two
> spaces in the return type name (plus two spots which used 2 spaces after
> single keyword return type instead of 1 which triggered my search regex as
> well).
>
> Tested on x86_64-linux, ok for trunk?
>
> 2023-12-01 Jakub Jelinek <jakub@redhat.com>
>
> * doc/extend.texi (__builtin_addc, __builtin_addcl, __builtin_addcll,
> __builtin_subc, __builtin_subcl, __builtin_subcll,
> __builtin_stdc_bit_width, __builtin_stdc_count_ones,
> __builtin_stdc_count_zeros, __builtin_stdc_first_leading_one,
> __builtin_stdc_first_leading_zero, __builtin_stdc_first_trailing_one,
> __builtin_stdc_first_trailing_zero, __builtin_stdc_has_single_bit,
> __builtin_stdc_leading_ones, __builtin_stdc_leading_zeros,
> __builtin_stdc_trailing_ones, __builtin_stdc_trailing_zeros,
> __builtin_nvptx_brev, __builtin_nvptx_brevll, __builtin_darn,
> __builtin_darn_raw, __builtin_ia32_vec_ext_v2di,
> __builtin_ia32_crc32qi, __builtin_ia32_crc32hi,
> __builtin_ia32_crc32si, __builtin_ia32_crc32di): Put {}s around
> return type with spaces in it.
> (__builtin_rx_mvfachi, __builtin_rx_mvfacmi): Remove superfluous
> whitespace.
OK
jeff
On 12/1/23 03:26, Jakub Jelinek wrote:
> Hi!
>
> In https://gcc.gnu.org/onlinedocs/gcc/Other-Builtins.html#index-_005f_005fbuiltin_005fstdc_005fbit_005ffloor>> I've noticed that while e.g. __builtin_stdc_bit_floor builtin is properly
> rendered in bold and bigger size, for the __builtin_stdc_bit_width builtin
> it is not the builtin name which is marked like that, but the keyword int
> before it. Also, seems such builtins are missing from the index.
>
> I've read the texinfo docs and they seem to suggest in
> https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Line-Macros.html>> that return types of functions with spaces in the return type should be
> wrapped with {}s and we already use that e.g. in
> @defbuiltin{{void *} __builtin_thread_pointer (void)}
>
> The following patch adjusts builtins I found which contained one or two
> spaces in the return type name (plus two spots which used 2 spaces after
> single keyword return type instead of 1 which triggered my search regex as
> well).
>
> Tested on x86_64-linux, ok for trunk?
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.
-Sandra
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?
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})
?
Jakub
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
@@ -13238,9 +13238,9 @@ after addition, conditional jump on carr
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_addc (unsigned int a, unsigned int b, unsigned int carry_in, unsigned int *carry_out)}
-@defbuiltinx{unsigned long int __builtin_addcl (unsigned long int a, unsigned long int b, unsigned int carry_in, unsigned long int *carry_out)}
-@defbuiltinx{unsigned long long int __builtin_addcll (unsigned long long int a, unsigned long long int b, unsigned long long int carry_in, unsigned long long int *carry_out)}
+@defbuiltin{{unsigned int} __builtin_addc (unsigned int a, unsigned int b, unsigned int carry_in, unsigned int *carry_out)}
+@defbuiltinx{{unsigned long int} __builtin_addcl (unsigned long int a, unsigned long int b, unsigned int carry_in, unsigned long int *carry_out)}
+@defbuiltinx{{unsigned long long int} __builtin_addcll (unsigned long long int a, unsigned long long int b, unsigned long long int carry_in, unsigned long long int *carry_out)}
These built-in functions are equivalent to:
@smallexample
@@ -13260,9 +13260,9 @@ emitted if one of them (preferrably the
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_subc (unsigned int a, unsigned int b, unsigned int carry_in, unsigned int *carry_out)}
-@defbuiltinx{unsigned long int __builtin_subcl (unsigned long int a, unsigned long int b, unsigned int carry_in, unsigned long int *carry_out)}
-@defbuiltinx{unsigned long long int __builtin_subcll (unsigned long long int a, unsigned long long int b, unsigned long long int carry_in, unsigned long long int *carry_out)}
+@defbuiltin{{unsigned int} __builtin_subc (unsigned int a, unsigned int b, unsigned int carry_in, unsigned int *carry_out)}
+@defbuiltinx{{unsigned long int} __builtin_subcl (unsigned long int a, unsigned long int b, unsigned int carry_in, unsigned long int *carry_out)}
+@defbuiltinx{{unsigned long long int} __builtin_subcll (unsigned long long int a, unsigned long long int b, unsigned long long int carry_in, unsigned long long int *carry_out)}
These built-in functions are equivalent to:
@smallexample
@@ -15167,7 +15167,7 @@ where @var{prec} is bit width of @var{ty
in @var{arg} are evaluated just once.
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_bit_width (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_bit_width (@var{type} @var{arg})}
The @code{__builtin_stdc_bit_width} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15176,7 +15176,7 @@ performed on the argument. It is equiva
where @var{prec} is bit width of @var{type}.
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_count_ones (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_count_ones (@var{type} @var{arg})}
The @code{__builtin_stdc_count_ones} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15184,7 +15184,7 @@ performed on the argument. It is equiva
@code{(unsigned int) __builtin_popcountg (@var{arg})}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_count_zeros (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_count_zeros (@var{type} @var{arg})}
The @code{__builtin_stdc_count_zeros} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15192,7 +15192,7 @@ performed on the argument. It is equiva
@code{(unsigned int) __builtin_popcountg ((@var{type}) ~@var{arg})}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_first_leading_one (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_first_leading_one (@var{type} @var{arg})}
The @code{__builtin_stdc_first_leading_one} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15200,7 +15200,7 @@ performed on the argument. It is equiva
@code{__builtin_clzg (@var{arg}, -1) + 1U}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_first_leading_zero (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_first_leading_zero (@var{type} @var{arg})}
The @code{__builtin_stdc_first_leading_zero} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15208,7 +15208,7 @@ performed on the argument. It is equiva
@code{__builtin_clzg ((@var{type}) ~@var{arg}, -1) + 1U}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_first_trailing_one (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_one (@var{type} @var{arg})}
The @code{__builtin_stdc_first_trailing_one} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15216,7 +15216,7 @@ performed on the argument. It is equiva
@code{__builtin_ctzg (@var{arg}, -1) + 1U}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_first_trailing_zero (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_first_trailing_zero (@var{type} @var{arg})}
The @code{__builtin_stdc_first_trailing_zero} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15224,7 +15224,7 @@ performed on the argument. It is equiva
@code{__builtin_ctzg ((@var{type}) ~@var{arg}, -1) + 1U}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_has_single_bit (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_has_single_bit (@var{type} @var{arg})}
The @code{__builtin_stdc_has_single_bit} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15232,7 +15232,7 @@ performed on the argument. It is equiva
@code{(_Bool) (__builtin_popcountg (@var{arg}) == 1)}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_leading_ones (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_leading_ones (@var{type} @var{arg})}
The @code{__builtin_stdc_leading_ones} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15240,7 +15240,7 @@ performed on the argument. It is equiva
@code{(unsigned int) __builtin_clzg ((@var{type}) ~@var{arg}, @var{prec})}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_leading_zeros (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_leading_zeros (@var{type} @var{arg})}
The @code{__builtin_stdc_leading_zeros} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15248,7 +15248,7 @@ performed on the argument. It is equiva
@code{(unsigned int) __builtin_clzg (@var{arg}, @var{prec})}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_trailing_ones (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_trailing_ones (@var{type} @var{arg})}
The @code{__builtin_stdc_trailing_ones} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -15256,7 +15256,7 @@ performed on the argument. It is equiva
@code{(unsigned int) __builtin_ctzg ((@var{type}) ~@var{arg}, @var{prec})}
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_stdc_trailing_zeros (@var{type} @var{arg})}
+@defbuiltin{{unsigned int} __builtin_stdc_trailing_zeros (@var{type} @var{arg})}
The @code{__builtin_stdc_trailing_zeros} function is available only
in C. It is type-generic, the argument can be any unsigned integer
(standard, extended or bit-precise). No integral argument promotions are
@@ -18731,11 +18731,11 @@ Disable global interrupt.
These built-in functions are available for the Nvidia PTX target:
-@defbuiltin{unsigned int __builtin_nvptx_brev (unsigned int @var{x})}
+@defbuiltin{{unsigned int} __builtin_nvptx_brev (unsigned int @var{x})}
Reverse the bit order of a 32-bit unsigned integer.
@enddefbuiltin
-@defbuiltin{unsigned long long __builtin_nvptx_brevll (unsigned long long @var{x})}
+@defbuiltin{{unsigned long long} __builtin_nvptx_brevll (unsigned long long @var{x})}
Reverse the bit order of a 64-bit unsigned integer.
@enddefbuiltin
@@ -19232,8 +19232,8 @@ round to odd as the rounding mode.
The following additional built-in functions are also available for the
PowerPC family of processors, starting with ISA 3.0 or later:
-@defbuiltin{long long __builtin_darn (void)}
-@defbuiltinx{long long __builtin_darn_raw (void)}
+@defbuiltin{{long long} __builtin_darn (void)}
+@defbuiltinx{{long long} __builtin_darn_raw (void)}
@defbuiltinx{int __builtin_darn_32 (void)}
The @code{__builtin_darn} and @code{__builtin_darn_raw}
functions require a
@@ -22317,12 +22317,12 @@ multiplying the bottom 16 bits of the tw
accumulator.
@enddefbuiltin
-@defbuiltin{int __builtin_rx_mvfachi (void)}
+@defbuiltin{int __builtin_rx_mvfachi (void)}
Generates the @code{mvfachi} machine instruction to read the top
32 bits of the accumulator.
@enddefbuiltin
-@defbuiltin{int __builtin_rx_mvfacmi (void)}
+@defbuiltin{int __builtin_rx_mvfacmi (void)}
Generates the @code{mvfacmi} machine instruction to read the middle
32 bits of the accumulator.
@enddefbuiltin
@@ -23691,7 +23691,7 @@ Generates the @code{extractps} machine i
Generates the @code{pextrd} machine instruction.
@enddefbuiltin
-@defbuiltin{long long __builtin_ia32_vec_ext_v2di (v2di, const int)}
+@defbuiltin{{long long} __builtin_ia32_vec_ext_v2di (v2di, const int)}
Generates the @code{pextrq} machine instruction in 64bit mode.
@enddefbuiltin
@@ -23720,19 +23720,19 @@ v2di __builtin_ia32_pcmpgtq (v2di, v2di)
The following built-in functions are available when @option{-msse4.2} is
used.
-@defbuiltin{unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char)}
+@defbuiltin{{unsigned int} __builtin_ia32_crc32qi (unsigned int, unsigned char)}
Generates the @code{crc32b} machine instruction.
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short)}
+@defbuiltin{{unsigned int} __builtin_ia32_crc32hi (unsigned int, unsigned short)}
Generates the @code{crc32w} machine instruction.
@enddefbuiltin
-@defbuiltin{unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int)}
+@defbuiltin{{unsigned int} __builtin_ia32_crc32si (unsigned int, unsigned int)}
Generates the @code{crc32l} machine instruction.
@enddefbuiltin
-@defbuiltin{unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long)}
+@defbuiltin{{unsigned long long} __builtin_ia32_crc32di (unsigned long long, unsigned long long)}
Generates the @code{crc32q} machine instruction.
@enddefbuiltin