* [PATCH 1/7] jit,docs: use enum directive for enumeral types
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
@ 2022-07-25 8:52 ` Martin Liska
2022-07-25 22:35 ` David Malcolm
2022-07-25 9:03 ` [PATCH 2/7] jit, docs: replace c:type:`int_type` with :expr:`int_type` Martin Liska
` (5 subsequent siblings)
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liska @ 2022-07-25 8:52 UTC (permalink / raw)
To: gcc-patches
gcc/jit/ChangeLog:
* docs/conf.py: Add needs_sphinx = '3.0' where c:type was added.
* docs/index.rst: Remove note about it.
* docs/topics/compilation.rst: Use enum directive and reference.
* docs/topics/contexts.rst: Likewise.
* docs/topics/expressions.rst: Likewise.
* docs/topics/functions.rst: Likewise.
---
gcc/jit/docs/conf.py | 3 +++
gcc/jit/docs/index.rst | 7 -------
gcc/jit/docs/topics/compilation.rst | 4 ++--
gcc/jit/docs/topics/contexts.rst | 6 +++---
gcc/jit/docs/topics/expressions.rst | 10 +++++-----
gcc/jit/docs/topics/functions.rst | 2 +-
6 files changed, 14 insertions(+), 18 deletions(-)
diff --git a/gcc/jit/docs/conf.py b/gcc/jit/docs/conf.py
index 00f0e9887dd..062232ae280 100644
--- a/gcc/jit/docs/conf.py
+++ b/gcc/jit/docs/conf.py
@@ -39,6 +39,9 @@ source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
+# c:type directive is supported since 3.0
+needs_sphinx = '3.0'
+
# General information about the project.
project = u'libgccjit'
copyright = u'2014-2022 Free Software Foundation, Inc.'
diff --git a/gcc/jit/docs/index.rst b/gcc/jit/docs/index.rst
index 3aff17d7a60..21c3140e238 100644
--- a/gcc/jit/docs/index.rst
+++ b/gcc/jit/docs/index.rst
@@ -45,10 +45,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
-
-.. Some notes:
-
- The Sphinx C domain appears to lack explicit support for enum values,
- so I've been using :c:macro: for them.
-
- See https://sphinx-doc.org/domains.html#the-c-domain
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index 9b1eed2dede..c5fa6eb0faf 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -158,14 +158,14 @@ For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`.
:c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
``output_path``, and insteads uses the given
-:c:type:`enum gcc_jit_output_kind` to decide what to do.
+:c:enum:`gcc_jit_output_kind` to decide what to do.
.. note::
This is different from the ``gcc`` program, which does make use of the
suffix of the output file when determining what to do.
-.. type:: enum gcc_jit_output_kind
+.. enum:: gcc_jit_output_kind
The available kinds of output are:
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index dfbe968e127..205b5f3dcf5 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -311,7 +311,7 @@ String Options
Set a string option of the context.
- .. type:: enum gcc_jit_str_option
+ .. enum:: gcc_jit_str_option
The parameter ``value`` can be NULL. If non-NULL, the call takes a
copy of the underlying string, so it is valid to pass in a pointer to
@@ -334,7 +334,7 @@ Boolean options
Set a boolean option of the context.
Zero is "false" (the default), non-zero is "true".
- .. type:: enum gcc_jit_bool_option
+ .. enum:: gcc_jit_bool_option
.. macro:: GCC_JIT_BOOL_OPTION_DEBUGINFO
@@ -513,7 +513,7 @@ Integer options
Set an integer option of the context.
- .. type:: enum gcc_jit_int_option
+ .. enum:: gcc_jit_int_option
There is just one integer option specified this way:
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 91ee8a9c74a..49b7e14ae2b 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -309,7 +309,7 @@ Unary Operations
The parameter ``result_type`` must be a numeric type.
-.. type:: enum gcc_jit_unary_op
+.. enum:: gcc_jit_unary_op
The available unary operations are:
@@ -376,7 +376,7 @@ Binary Operations
The parameter ``result_type`` must be a numeric type.
-.. type:: enum gcc_jit_binary_op
+.. enum:: gcc_jit_binary_op
The available binary operations are:
@@ -534,7 +534,7 @@ Comparisons
Build a boolean rvalue out of the comparison of two other rvalues.
-.. type:: enum gcc_jit_comparison
+.. enum:: gcc_jit_comparison
======================================= ============
Comparison C equivalent
@@ -711,7 +711,7 @@ where the rvalue is computed by reading from the storage area.
The "model" parameter determines the thread-local storage model of the "lvalue":
- .. type:: enum gcc_jit_tls_model
+ .. enum:: gcc_jit_tls_model
.. c:macro:: GCC_JIT_TLS_MODEL_NONE
@@ -841,7 +841,7 @@ Global variables
The "kind" parameter determines the visibility of the "global" outside
of the :c:type:`gcc_jit_result`:
- .. type:: enum gcc_jit_global_kind
+ .. enum:: gcc_jit_global_kind
.. c:macro:: GCC_JIT_GLOBAL_EXPORTED
diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst
index 0845fe0f7d3..d6d4fe90834 100644
--- a/gcc/jit/docs/topics/functions.rst
+++ b/gcc/jit/docs/topics/functions.rst
@@ -80,7 +80,7 @@ Functions
Create a gcc_jit_function with the given name and parameters.
- .. type:: enum gcc_jit_function_kind
+ .. enum:: gcc_jit_function_kind
This enum controls the kind of function created, and has the following
values:
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* [PATCH 2/7] jit, docs: replace c:type:`int_type` with :expr:`int_type`
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
2022-07-25 8:52 ` [PATCH 1/7] jit,docs: use enum directive for enumeral types Martin Liska
@ 2022-07-25 9:03 ` Martin Liska
2022-07-25 22:37 ` [PATCH 2/7] jit,docs: " David Malcolm
2022-07-25 9:15 ` [PATCH 3/7] jit,docs: various fixes Martin Liska
` (4 subsequent siblings)
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liska @ 2022-07-25 9:03 UTC (permalink / raw)
To: gcc-patches
Use expression that work fine for basic type.
gcc/jit/ChangeLog:
* docs/cp/topics/expressions.rst: Use :expr: for basic types.
* docs/topics/compilation.rst: Likewise.
* docs/topics/expressions.rst: Likewise.
* docs/topics/function-pointers.rst: Likewise.
---
gcc/jit/docs/cp/topics/expressions.rst | 6 +++---
gcc/jit/docs/topics/compilation.rst | 4 ++--
gcc/jit/docs/topics/expressions.rst | 6 +++---
gcc/jit/docs/topics/function-pointers.rst | 2 +-
4 files changed, 9 insertions(+), 9 deletions(-)
diff --git a/gcc/jit/docs/cp/topics/expressions.rst b/gcc/jit/docs/cp/topics/expressions.rst
index 239e004371e..003dbce8991 100644
--- a/gcc/jit/docs/cp/topics/expressions.rst
+++ b/gcc/jit/docs/cp/topics/expressions.rst
@@ -57,14 +57,14 @@ Simple expressions
int value) const
Given a numeric type (integer or floating point), build an rvalue for
- the given constant :c:type:`int` value.
+ the given constant :expr:`int` value.
.. function:: gccjit::rvalue \
gccjit::context::new_rvalue (gccjit::type numeric_type, \
long value) const
Given a numeric type (integer or floating point), build an rvalue for
- the given constant :c:type:`long` value.
+ the given constant :expr:`long` value.
.. function:: gccjit::rvalue \
gccjit::context::zero (gccjit::type numeric_type) const
@@ -91,7 +91,7 @@ Simple expressions
double value) const
Given a numeric type (integer or floating point), build an rvalue for
- the given constant :c:type:`double` value.
+ the given constant :expr:`double` value.
.. function:: gccjit::rvalue \
gccjit::context::new_rvalue (gccjit::type pointer_type, \
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index c5fa6eb0faf..91b9c2533cf 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -98,8 +98,8 @@ In-memory compilation
If the global is found, the result will need to be cast to a
pointer of the correct type before it can be called.
- This is a *pointer* to the global, so e.g. for an :c:type:`int` this is
- an :c:type:`int *`.
+ This is a *pointer* to the global, so e.g. for an :expr:`int` this is
+ an :expr:`int *`.
For example, given an ``int foo;`` created this way:
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 49b7e14ae2b..00e2ec8cfeb 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -60,7 +60,7 @@ Simple expressions
int value)
Given a numeric type (integer or floating point), build an rvalue for
- the given constant :c:type:`int` value.
+ the given constant :expr:`int` value.
.. function:: gcc_jit_rvalue *\
gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \
@@ -68,7 +68,7 @@ Simple expressions
long value)
Given a numeric type (integer or floating point), build an rvalue for
- the given constant :c:type:`long` value.
+ the given constant :expr:`long` value.
.. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
gcc_jit_type *numeric_type)
@@ -96,7 +96,7 @@ Simple expressions
double value)
Given a numeric type (integer or floating point), build an rvalue for
- the given constant :c:type:`double` value.
+ the given constant :expr:`double` value.
.. function:: gcc_jit_rvalue *\
gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
diff --git a/gcc/jit/docs/topics/function-pointers.rst b/gcc/jit/docs/topics/function-pointers.rst
index e6f9970a7a7..dde49215853 100644
--- a/gcc/jit/docs/topics/function-pointers.rst
+++ b/gcc/jit/docs/topics/function-pointers.rst
@@ -48,7 +48,7 @@ to it in :c:type:`gcc_jit_rvalue` form using
type obtained using :c:func:`gcc_jit_context_new_function_ptr_type`.
Here's an example of creating a function pointer type corresponding to C's
-:c:type:`void (*) (int, int, int)`:
+:expr:`void (*) (int, int, int)`:
.. code-block:: c
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 2/7] jit,docs: replace c:type:`int_type` with :expr:`int_type`
2022-07-25 9:03 ` [PATCH 2/7] jit, docs: replace c:type:`int_type` with :expr:`int_type` Martin Liska
@ 2022-07-25 22:37 ` David Malcolm
2022-07-26 4:48 ` Martin Liška
0 siblings, 1 reply; 20+ messages in thread
From: David Malcolm @ 2022-07-25 22:37 UTC (permalink / raw)
To: Martin Liska, gcc-patches
On Mon, 2022-07-25 at 11:03 +0200, Martin Liska wrote:
> Use expression that work fine for basic type.
What's the motivation for this change? Surely the things being marked
up are types, rather than expressions?
Dave
>
> gcc/jit/ChangeLog:
>
> * docs/cp/topics/expressions.rst: Use :expr: for basic types.
> * docs/topics/compilation.rst: Likewise.
> * docs/topics/expressions.rst: Likewise.
> * docs/topics/function-pointers.rst: Likewise.
> ---
> gcc/jit/docs/cp/topics/expressions.rst | 6 +++---
> gcc/jit/docs/topics/compilation.rst | 4 ++--
> gcc/jit/docs/topics/expressions.rst | 6 +++---
> gcc/jit/docs/topics/function-pointers.rst | 2 +-
> 4 files changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/gcc/jit/docs/cp/topics/expressions.rst
> b/gcc/jit/docs/cp/topics/expressions.rst
> index 239e004371e..003dbce8991 100644
> --- a/gcc/jit/docs/cp/topics/expressions.rst
> +++ b/gcc/jit/docs/cp/topics/expressions.rst
> @@ -57,14 +57,14 @@ Simple expressions
> int value) const
>
> Given a numeric type (integer or floating point), build an rvalue
> for
> - the given constant :c:type:`int` value.
> + the given constant :expr:`int` value.
>
> .. function:: gccjit::rvalue \
> gccjit::context::new_rvalue (gccjit::type
> numeric_type, \
> long value) const
>
> Given a numeric type (integer or floating point), build an rvalue
> for
> - the given constant :c:type:`long` value.
> + the given constant :expr:`long` value.
>
> .. function:: gccjit::rvalue \
> gccjit::context::zero (gccjit::type numeric_type)
> const
> @@ -91,7 +91,7 @@ Simple expressions
> double value) const
>
> Given a numeric type (integer or floating point), build an rvalue
> for
> - the given constant :c:type:`double` value.
> + the given constant :expr:`double` value.
>
> .. function:: gccjit::rvalue \
> gccjit::context::new_rvalue (gccjit::type
> pointer_type, \
> diff --git a/gcc/jit/docs/topics/compilation.rst
> b/gcc/jit/docs/topics/compilation.rst
> index c5fa6eb0faf..91b9c2533cf 100644
> --- a/gcc/jit/docs/topics/compilation.rst
> +++ b/gcc/jit/docs/topics/compilation.rst
> @@ -98,8 +98,8 @@ In-memory compilation
> If the global is found, the result will need to be cast to a
> pointer of the correct type before it can be called.
>
> - This is a *pointer* to the global, so e.g. for an :c:type:`int`
> this is
> - an :c:type:`int *`.
> + This is a *pointer* to the global, so e.g. for an :expr:`int`
> this is
> + an :expr:`int *`.
>
> For example, given an ``int foo;`` created this way:
>
> diff --git a/gcc/jit/docs/topics/expressions.rst
> b/gcc/jit/docs/topics/expressions.rst
> index 49b7e14ae2b..00e2ec8cfeb 100644
> --- a/gcc/jit/docs/topics/expressions.rst
> +++ b/gcc/jit/docs/topics/expressions.rst
> @@ -60,7 +60,7 @@ Simple expressions
> int value)
>
> Given a numeric type (integer or floating point), build an rvalue
> for
> - the given constant :c:type:`int` value.
> + the given constant :expr:`int` value.
>
> .. function:: gcc_jit_rvalue *\
> gcc_jit_context_new_rvalue_from_long (gcc_jit_context
> *ctxt, \
> @@ -68,7 +68,7 @@ Simple expressions
> long value)
>
> Given a numeric type (integer or floating point), build an rvalue
> for
> - the given constant :c:type:`long` value.
> + the given constant :expr:`long` value.
>
> .. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context
> *ctxt, \
> gcc_jit_type
> *numeric_type)
> @@ -96,7 +96,7 @@ Simple expressions
> double value)
>
> Given a numeric type (integer or floating point), build an rvalue
> for
> - the given constant :c:type:`double` value.
> + the given constant :expr:`double` value.
>
> .. function:: gcc_jit_rvalue *\
> gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context
> *ctxt, \
> diff --git a/gcc/jit/docs/topics/function-pointers.rst
> b/gcc/jit/docs/topics/function-pointers.rst
> index e6f9970a7a7..dde49215853 100644
> --- a/gcc/jit/docs/topics/function-pointers.rst
> +++ b/gcc/jit/docs/topics/function-pointers.rst
> @@ -48,7 +48,7 @@ to it in :c:type:`gcc_jit_rvalue` form using
> type obtained using :c:func:`gcc_jit_context_new_function_ptr_type`.
>
> Here's an example of creating a function pointer type corresponding
> to C's
> -:c:type:`void (*) (int, int, int)`:
> +:expr:`void (*) (int, int, int)`:
>
> .. code-block:: c
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 2/7] jit,docs: replace c:type:`int_type` with :expr:`int_type`
2022-07-25 22:37 ` [PATCH 2/7] jit,docs: " David Malcolm
@ 2022-07-26 4:48 ` Martin Liška
2022-07-26 15:42 ` David Malcolm
0 siblings, 1 reply; 20+ messages in thread
From: Martin Liška @ 2022-07-26 4:48 UTC (permalink / raw)
To: David Malcolm, gcc-patches
On 7/26/22 00:37, David Malcolm wrote:
> On Mon, 2022-07-25 at 11:03 +0200, Martin Liska wrote:
>> Use expression that work fine for basic type.
>
> What's the motivation for this change? Surely the things being marked
> up are types, rather than expressions?
Problem is that one can't reference a type that is not defined by a :type: directive,
that's why I'm using :expr:
Fixes the following Sphinx warnings:
/home/marxin/Programming/gcc/gcc/jit/docs/topics/expressions.rst:70: WARNING: Unparseable C cross-reference: 'long'
Invalid C declaration: Expected identifier in nested name, got keyword: long [error at 4]
long
----^
Martin
>
> Dave
>
>>
>> gcc/jit/ChangeLog:
>>
>> * docs/cp/topics/expressions.rst: Use :expr: for basic types.
>> * docs/topics/compilation.rst: Likewise.
>> * docs/topics/expressions.rst: Likewise.
>> * docs/topics/function-pointers.rst: Likewise.
>> ---
>> gcc/jit/docs/cp/topics/expressions.rst | 6 +++---
>> gcc/jit/docs/topics/compilation.rst | 4 ++--
>> gcc/jit/docs/topics/expressions.rst | 6 +++---
>> gcc/jit/docs/topics/function-pointers.rst | 2 +-
>> 4 files changed, 9 insertions(+), 9 deletions(-)
>>
>> diff --git a/gcc/jit/docs/cp/topics/expressions.rst
>> b/gcc/jit/docs/cp/topics/expressions.rst
>> index 239e004371e..003dbce8991 100644
>> --- a/gcc/jit/docs/cp/topics/expressions.rst
>> +++ b/gcc/jit/docs/cp/topics/expressions.rst
>> @@ -57,14 +57,14 @@ Simple expressions
>> int value) const
>>
>> Given a numeric type (integer or floating point), build an rvalue
>> for
>> - the given constant :c:type:`int` value.
>> + the given constant :expr:`int` value.
>>
>> .. function:: gccjit::rvalue \
>> gccjit::context::new_rvalue (gccjit::type
>> numeric_type, \
>> long value) const
>>
>> Given a numeric type (integer or floating point), build an rvalue
>> for
>> - the given constant :c:type:`long` value.
>> + the given constant :expr:`long` value.
>>
>> .. function:: gccjit::rvalue \
>> gccjit::context::zero (gccjit::type numeric_type)
>> const
>> @@ -91,7 +91,7 @@ Simple expressions
>> double value) const
>>
>> Given a numeric type (integer or floating point), build an rvalue
>> for
>> - the given constant :c:type:`double` value.
>> + the given constant :expr:`double` value.
>>
>> .. function:: gccjit::rvalue \
>> gccjit::context::new_rvalue (gccjit::type
>> pointer_type, \
>> diff --git a/gcc/jit/docs/topics/compilation.rst
>> b/gcc/jit/docs/topics/compilation.rst
>> index c5fa6eb0faf..91b9c2533cf 100644
>> --- a/gcc/jit/docs/topics/compilation.rst
>> +++ b/gcc/jit/docs/topics/compilation.rst
>> @@ -98,8 +98,8 @@ In-memory compilation
>> If the global is found, the result will need to be cast to a
>> pointer of the correct type before it can be called.
>>
>> - This is a *pointer* to the global, so e.g. for an :c:type:`int`
>> this is
>> - an :c:type:`int *`.
>> + This is a *pointer* to the global, so e.g. for an :expr:`int`
>> this is
>> + an :expr:`int *`.
>>
>> For example, given an ``int foo;`` created this way:
>>
>> diff --git a/gcc/jit/docs/topics/expressions.rst
>> b/gcc/jit/docs/topics/expressions.rst
>> index 49b7e14ae2b..00e2ec8cfeb 100644
>> --- a/gcc/jit/docs/topics/expressions.rst
>> +++ b/gcc/jit/docs/topics/expressions.rst
>> @@ -60,7 +60,7 @@ Simple expressions
>> int value)
>>
>> Given a numeric type (integer or floating point), build an rvalue
>> for
>> - the given constant :c:type:`int` value.
>> + the given constant :expr:`int` value.
>>
>> .. function:: gcc_jit_rvalue *\
>> gcc_jit_context_new_rvalue_from_long (gcc_jit_context
>> *ctxt, \
>> @@ -68,7 +68,7 @@ Simple expressions
>> long value)
>>
>> Given a numeric type (integer or floating point), build an rvalue
>> for
>> - the given constant :c:type:`long` value.
>> + the given constant :expr:`long` value.
>>
>> .. function:: gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context
>> *ctxt, \
>> gcc_jit_type
>> *numeric_type)
>> @@ -96,7 +96,7 @@ Simple expressions
>> double value)
>>
>> Given a numeric type (integer or floating point), build an rvalue
>> for
>> - the given constant :c:type:`double` value.
>> + the given constant :expr:`double` value.
>>
>> .. function:: gcc_jit_rvalue *\
>> gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context
>> *ctxt, \
>> diff --git a/gcc/jit/docs/topics/function-pointers.rst
>> b/gcc/jit/docs/topics/function-pointers.rst
>> index e6f9970a7a7..dde49215853 100644
>> --- a/gcc/jit/docs/topics/function-pointers.rst
>> +++ b/gcc/jit/docs/topics/function-pointers.rst
>> @@ -48,7 +48,7 @@ to it in :c:type:`gcc_jit_rvalue` form using
>> type obtained using :c:func:`gcc_jit_context_new_function_ptr_type`.
>>
>> Here's an example of creating a function pointer type corresponding
>> to C's
>> -:c:type:`void (*) (int, int, int)`:
>> +:expr:`void (*) (int, int, int)`:
>>
>> .. code-block:: c
>>
>
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 2/7] jit,docs: replace c:type:`int_type` with :expr:`int_type`
2022-07-26 4:48 ` Martin Liška
@ 2022-07-26 15:42 ` David Malcolm
0 siblings, 0 replies; 20+ messages in thread
From: David Malcolm @ 2022-07-26 15:42 UTC (permalink / raw)
To: Martin Liška, gcc-patches
On Tue, 2022-07-26 at 06:48 +0200, Martin Liška wrote:
> On 7/26/22 00:37, David Malcolm wrote:
> > On Mon, 2022-07-25 at 11:03 +0200, Martin Liska wrote:
> > > Use expression that work fine for basic type.
> >
> > What's the motivation for this change? Surely the things being
> > marked
> > up are types, rather than expressions?
>
> Problem is that one can't reference a type that is not defined by a
> :type: directive,
> that's why I'm using :expr:
>
> Fixes the following Sphinx warnings:
>
> /home/marxin/Programming/gcc/gcc/jit/docs/topics/expressions.rst:70:
> WARNING: Unparseable C cross-reference: 'long'
> Invalid C declaration: Expected identifier in nested name, got
> keyword: long [error at 4]
> long
> ----^
Fair enough, thanks. LGTM.
Dave
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 3/7] jit,docs: various fixes
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
2022-07-25 8:52 ` [PATCH 1/7] jit,docs: use enum directive for enumeral types Martin Liska
2022-07-25 9:03 ` [PATCH 2/7] jit, docs: replace c:type:`int_type` with :expr:`int_type` Martin Liska
@ 2022-07-25 9:15 ` Martin Liska
2022-07-25 22:39 ` David Malcolm
2022-07-25 9:51 ` [PATCH 4/7] jit,docs: compact function declarations Martin Liska
` (3 subsequent siblings)
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liska @ 2022-07-25 9:15 UTC (permalink / raw)
To: gcc-patches
gcc/jit/ChangeLog:
* docs/cp/intro/tutorial02.rst: Use proper reference.
* docs/cp/topics/contexts.rst: Likewise.
* docs/cp/topics/functions.rst: Put `class` directive before a
function as it is not allowed declaring a class in a fn.
* docs/cp/topics/types.rst: Add template keyword.
* docs/examples/tut04-toyvm/toyvm.c (toyvm_function_compile):
Add removed comment used for code snippet ending detection.
* docs/intro/tutorial04.rst: Fix to match the real comment.
---
gcc/jit/docs/cp/intro/tutorial02.rst | 2 +-
gcc/jit/docs/cp/topics/contexts.rst | 2 +-
gcc/jit/docs/cp/topics/functions.rst | 46 +++++++++++------------
gcc/jit/docs/cp/topics/types.rst | 2 +-
gcc/jit/docs/examples/tut04-toyvm/toyvm.c | 1 +
gcc/jit/docs/intro/tutorial04.rst | 2 +-
6 files changed, 28 insertions(+), 27 deletions(-)
diff --git a/gcc/jit/docs/cp/intro/tutorial02.rst b/gcc/jit/docs/cp/intro/tutorial02.rst
index 2064f8e4dd9..55675cc7398 100644
--- a/gcc/jit/docs/cp/intro/tutorial02.rst
+++ b/gcc/jit/docs/cp/intro/tutorial02.rst
@@ -121,7 +121,7 @@ in this case just one:
params.push_back (param_i);
Now we can create the function, using
-:c:func:`gccjit::context::new_function`:
+:cpp:func:`gccjit::context::new_function`:
.. code-block:: c++
diff --git a/gcc/jit/docs/cp/topics/contexts.rst b/gcc/jit/docs/cp/topics/contexts.rst
index e5bccfb807d..f60f2102b3e 100644
--- a/gcc/jit/docs/cp/topics/contexts.rst
+++ b/gcc/jit/docs/cp/topics/contexts.rst
@@ -141,7 +141,7 @@ Debugging
If "update_locations" is true, then also set up :class:`gccjit::location`
information throughout the context, pointing at the dump file as if it
were a source file. This may be of use in conjunction with
- :c:macro:`GCCJIT::BOOL_OPTION_DEBUGINFO` to allow stepping through the
+ :c:macro:`GCC_JIT_BOOL_OPTION_DEBUGINFO` to allow stepping through the
code in a debugger.
.. function:: void\
diff --git a/gcc/jit/docs/cp/topics/functions.rst b/gcc/jit/docs/cp/topics/functions.rst
index 0e266abc70c..4e325ac3fef 100644
--- a/gcc/jit/docs/cp/topics/functions.rst
+++ b/gcc/jit/docs/cp/topics/functions.rst
@@ -243,6 +243,29 @@ Statements
return;
+.. class:: gccjit::case_
+
+ A `gccjit::case_` represents a case within a switch statement, and
+ is created within a particular :class:`gccjit::context` using
+ :func:`gccjit::context::new_case`. It is a subclass of
+ :class:`gccjit::object`.
+
+ Each case expresses a multivalued range of integer values. You
+ can express single-valued cases by passing in the same value for
+ both `min_value` and `max_value`.
+
+.. function:: gccjit::case_ *\
+ gccjit::context::new_case (gccjit::rvalue min_value,\
+ gccjit::rvalue max_value,\
+ gccjit::block dest_block)
+
+ Create a new gccjit::case for use in a switch statement.
+ `min_value` and `max_value` must be constants of an integer type,
+ which must match that of the expression of the switch statement.
+
+ `dest_block` must be within the same function as the switch
+ statement.
+
.. function:: void\
gccjit::block::end_with_switch (gccjit::rvalue expr,\
gccjit::block default_block,\
@@ -292,29 +315,6 @@ Statements
#ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
- .. class:: gccjit::case_
-
- A `gccjit::case_` represents a case within a switch statement, and
- is created within a particular :class:`gccjit::context` using
- :func:`gccjit::context::new_case`. It is a subclass of
- :class:`gccjit::object`.
-
- Each case expresses a multivalued range of integer values. You
- can express single-valued cases by passing in the same value for
- both `min_value` and `max_value`.
-
- .. function:: gccjit::case_ *\
- gccjit::context::new_case (gccjit::rvalue min_value,\
- gccjit::rvalue max_value,\
- gccjit::block dest_block)
-
- Create a new gccjit::case for use in a switch statement.
- `min_value` and `max_value` must be constants of an integer type,
- which must match that of the expression of the switch statement.
-
- `dest_block` must be within the same function as the switch
- statement.
-
Here's an example of creating a switch statement:
.. literalinclude:: ../../../../testsuite/jit.dg/test-switch.cc
diff --git a/gcc/jit/docs/cp/topics/types.rst b/gcc/jit/docs/cp/topics/types.rst
index c695ceb3098..5d50a39b9d0 100644
--- a/gcc/jit/docs/cp/topics/types.rst
+++ b/gcc/jit/docs/cp/topics/types.rst
@@ -65,7 +65,7 @@ Standard types
Access the integer type of the given size.
-.. function:: gccjit::type \
+.. function:: template<typename T> gccjit::type \
gccjit::context::get_int_type <T> ()
Access the given integer type. For example, you could map the
diff --git a/gcc/jit/docs/examples/tut04-toyvm/toyvm.c b/gcc/jit/docs/examples/tut04-toyvm/toyvm.c
index 8334b975163..c2333f0de89 100644
--- a/gcc/jit/docs/examples/tut04-toyvm/toyvm.c
+++ b/gcc/jit/docs/examples/tut04-toyvm/toyvm.c
@@ -764,6 +764,7 @@ toyvm_function_compile (toyvm_function *fn)
toyvm_result->cf_code =
(toyvm_compiled_code)gcc_jit_result_get_code (jit_result,
funcname);
+ /* (this leaks "jit_result" and "funcname") */
free (funcname);
diff --git a/gcc/jit/docs/intro/tutorial04.rst b/gcc/jit/docs/intro/tutorial04.rst
index e1c47a0d2d5..89098876530 100644
--- a/gcc/jit/docs/intro/tutorial04.rst
+++ b/gcc/jit/docs/intro/tutorial04.rst
@@ -308,7 +308,7 @@ We can now compile it, and extract machine code from the result:
.. literalinclude:: ../examples/tut04-toyvm/toyvm.c
:start-after: /* We've now finished populating the context. Compile it. */
- :end-before: /* (this leaks "result" and "funcname") */
+ :end-before: /* (this leaks "jit_result" and "funcname") */
:language: c
We can now run the result:
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 3/7] jit,docs: various fixes
2022-07-25 9:15 ` [PATCH 3/7] jit,docs: various fixes Martin Liska
@ 2022-07-25 22:39 ` David Malcolm
0 siblings, 0 replies; 20+ messages in thread
From: David Malcolm @ 2022-07-25 22:39 UTC (permalink / raw)
To: Martin Liska, gcc-patches
On Mon, 2022-07-25 at 11:15 +0200, Martin Liska wrote:
> gcc/jit/ChangeLog:
>
> * docs/cp/intro/tutorial02.rst: Use proper reference.
> * docs/cp/topics/contexts.rst: Likewise.
> * docs/cp/topics/functions.rst: Put `class` directive before
> a
> function as it is not allowed declaring a class in a fn.
> * docs/cp/topics/types.rst: Add template keyword.
> * docs/examples/tut04-toyvm/toyvm.c (toyvm_function_compile):
> Add removed comment used for code snippet ending detection.
> * docs/intro/tutorial04.rst: Fix to match the real comment.
Thanks, looks good to me.
Dave
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 4/7] jit,docs: compact function declarations
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
` (2 preceding siblings ...)
2022-07-25 9:15 ` [PATCH 3/7] jit,docs: various fixes Martin Liska
@ 2022-07-25 9:51 ` Martin Liska
2022-07-25 22:39 ` David Malcolm
2022-07-25 10:35 ` [PATCH 5/7] jit,docs: use list-table instead of fixed table Martin Liska
` (2 subsequent siblings)
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liska @ 2022-07-25 9:51 UTC (permalink / raw)
To: gcc-patches
gcc/jit/ChangeLog:
* docs/cp/topics/expressions.rst: Compact so that the generated
output is also more compact.
---
gcc/jit/docs/cp/topics/expressions.rst | 42 +++++++++-----------------
1 file changed, 14 insertions(+), 28 deletions(-)
diff --git a/gcc/jit/docs/cp/topics/expressions.rst b/gcc/jit/docs/cp/topics/expressions.rst
index 003dbce8991..dec5b477811 100644
--- a/gcc/jit/docs/cp/topics/expressions.rst
+++ b/gcc/jit/docs/cp/topics/expressions.rst
@@ -236,48 +236,39 @@ operation:
gccjit::context::new_plus (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_minus (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_mult (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_divide (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_modulo (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_bitwise_and (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_bitwise_xor (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_bitwise_or (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_logical_and (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_logical_or (gccjit::type result_type, \
gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
@@ -375,24 +366,19 @@ operation:
.. function:: gccjit::rvalue \
gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
-
-.. function:: gccjit::rvalue \
+ gccjit::rvalue \
gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, \
gccjit::location loc)
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* [PATCH 5/7] jit,docs: use list-table instead of fixed table
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
` (3 preceding siblings ...)
2022-07-25 9:51 ` [PATCH 4/7] jit,docs: compact function declarations Martin Liska
@ 2022-07-25 10:35 ` Martin Liska
2022-07-25 22:40 ` David Malcolm
2022-07-25 12:39 ` [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type Martin Liska
2022-07-26 4:55 ` [PATCH 7/7] jit,docs: remove :ref:`modindex` Martin Liška
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liska @ 2022-07-25 10:35 UTC (permalink / raw)
To: gcc-patches
Use rather list-table that is easible to maintainer and one
does not have to wrap lines. Moreover, it provides great
attribute :widths: that correctly works (tested for HTML and PDF).
gcc/jit/ChangeLog:
* docs/cp/intro/tutorial04.rst: Use list-table.
* docs/intro/tutorial04.rst: Likewise.
* docs/intro/tutorial05.rst: Likewise.
* docs/topics/compilation.rst: Likewise.
* docs/topics/expressions.rst: Likewise.
* docs/topics/types.rst: Likewise.
---
gcc/jit/docs/cp/intro/tutorial04.rst | 73 ++++++++++++------
gcc/jit/docs/intro/tutorial04.rst | 73 ++++++++++++------
gcc/jit/docs/intro/tutorial05.rst | 37 +++++----
gcc/jit/docs/topics/compilation.rst | 22 ++++--
gcc/jit/docs/topics/expressions.rst | 97 ++++++++++++++---------
gcc/jit/docs/topics/types.rst | 111 +++++++++++++++++----------
6 files changed, 270 insertions(+), 143 deletions(-)
diff --git a/gcc/jit/docs/cp/intro/tutorial04.rst b/gcc/jit/docs/cp/intro/tutorial04.rst
index 45198ce3d7a..66dcce903c6 100644
--- a/gcc/jit/docs/cp/intro/tutorial04.rst
+++ b/gcc/jit/docs/cp/intro/tutorial04.rst
@@ -50,30 +50,55 @@ Naturally, a real interpreter would be much more complicated that this.
The following operations are supported:
-====================== ======================== =============== ==============
-Operation Meaning Old Stack New Stack
-====================== ======================== =============== ==============
-DUP Duplicate top of stack. ``[..., x]`` ``[..., x, x]``
-ROT Swap top two elements ``[..., x, y]`` ``[..., y, x]``
- of stack.
-BINARY_ADD Add the top two elements ``[..., x, y]`` ``[..., (x+y)]``
- on the stack.
-BINARY_SUBTRACT Likewise, but subtract. ``[..., x, y]`` ``[..., (x-y)]``
-BINARY_MULT Likewise, but multiply. ``[..., x, y]`` ``[..., (x*y)]``
-BINARY_COMPARE_LT Compare the top two ``[..., x, y]`` ``[..., (x<y)]``
- elements on the stack
- and push a nonzero/zero
- if (x<y).
-RECURSE Recurse, passing the top ``[..., x]`` ``[..., fn(x)]``
- of the stack, and
- popping the result.
-RETURN Return the top of the ``[x]`` ``[]``
- stack.
-PUSH_CONST `arg` Push an int const. ``[...]`` ``[..., arg]``
-JUMP_ABS_IF_TRUE `arg` Pop; if top of stack was ``[..., x]`` ``[...]``
- nonzero, jump to
- ``arg``.
-====================== ======================== =============== ==============
+.. list-table::
+ :header-rows: 1
+ :widths: 35 50 25 25
+
+ * - Operation
+ - Meaning
+ - Old Stack
+ - New Stack
+
+ * - DUP
+ - Duplicate top of stack.
+ - ``[..., x]``
+ - ``[..., x, x]``
+ * - ROT
+ - Swap top two elements of stack.
+ - ``[..., x, y]``
+ - ``[..., y, x]``
+ * - BINARY_ADD
+ - Add the top two elements on the stack.
+ - ``[..., x, y]``
+ - ``[..., (x+y)]``
+ * - BINARY_SUBTRACT
+ - Likewise, but subtract.
+ - ``[..., x, y]``
+ - ``[..., (x-y)]``
+ * - BINARY_MULT
+ - Likewise, but multiply.
+ - ``[..., x, y]``
+ - ``[..., (x*y)]``
+ * - BINARY_COMPARE_LT
+ - Compare the top two elements on the stack and push a nonzero/zero if (x<y).
+ - ``[..., x, y]``
+ - ``[..., (x<y)]``
+ * - RECURSE
+ - Recurse, passing the top of the stack, and popping the result.
+ - ``[..., x]``
+ - ``[..., fn(x)]``
+ * - RETURN
+ - Return the top of the stack.
+ - ``[x]``
+ - ``[]``
+ * - PUSH_CONST `arg`
+ - Push an int const.
+ - ``[...]``
+ - ``[..., arg]``
+ * - JUMP_ABS_IF_TRUE `arg`
+ - Pop; if top of stack was nonzero, jump to ``arg``.
+ - ``[..., x]``
+ - ``[...]``
Programs can be interpreted, disassembled, and compiled to machine code.
diff --git a/gcc/jit/docs/intro/tutorial04.rst b/gcc/jit/docs/intro/tutorial04.rst
index 89098876530..c2e3fb5c054 100644
--- a/gcc/jit/docs/intro/tutorial04.rst
+++ b/gcc/jit/docs/intro/tutorial04.rst
@@ -48,30 +48,55 @@ Naturally, a real interpreter would be much more complicated that this.
The following operations are supported:
-====================== ======================== =============== ==============
-Operation Meaning Old Stack New Stack
-====================== ======================== =============== ==============
-DUP Duplicate top of stack. ``[..., x]`` ``[..., x, x]``
-ROT Swap top two elements ``[..., x, y]`` ``[..., y, x]``
- of stack.
-BINARY_ADD Add the top two elements ``[..., x, y]`` ``[..., (x+y)]``
- on the stack.
-BINARY_SUBTRACT Likewise, but subtract. ``[..., x, y]`` ``[..., (x-y)]``
-BINARY_MULT Likewise, but multiply. ``[..., x, y]`` ``[..., (x*y)]``
-BINARY_COMPARE_LT Compare the top two ``[..., x, y]`` ``[..., (x<y)]``
- elements on the stack
- and push a nonzero/zero
- if (x<y).
-RECURSE Recurse, passing the top ``[..., x]`` ``[..., fn(x)]``
- of the stack, and
- popping the result.
-RETURN Return the top of the ``[x]`` ``[]``
- stack.
-PUSH_CONST `arg` Push an int const. ``[...]`` ``[..., arg]``
-JUMP_ABS_IF_TRUE `arg` Pop; if top of stack was ``[..., x]`` ``[...]``
- nonzero, jump to
- ``arg``.
-====================== ======================== =============== ==============
+.. list-table::
+ :header-rows: 1
+ :widths: 35 50 25 25
+
+ * - Operation
+ - Meaning
+ - Old Stack
+ - New Stack
+
+ * - DUP
+ - Duplicate top of stack.
+ - ``[..., x]``
+ - ``[..., x, x]``
+ * - ROT
+ - Swap top two elements of stack.
+ - ``[..., x, y]``
+ - ``[..., y, x]``
+ * - BINARY_ADD
+ - Add the top two elements on the stack.
+ - ``[..., x, y]``
+ - ``[..., (x+y)]``
+ * - BINARY_SUBTRACT
+ - Likewise, but subtract.
+ - ``[..., x, y]``
+ - ``[..., (x-y)]``
+ * - BINARY_MULT
+ - Likewise, but multiply.
+ - ``[..., x, y]``
+ - ``[..., (x*y)]``
+ * - BINARY_COMPARE_LT
+ - Compare the top two elements on the stack and push a nonzero/zero if (x<y).
+ - ``[..., x, y]``
+ - ``[..., (x<y)]``
+ * - RECURSE
+ - Recurse, passing the top of the stack, and popping the result.
+ - ``[..., x]``
+ - ``[..., fn(x)]``
+ * - RETURN
+ - Return the top of the stack.
+ - ``[x]``
+ - ``[]``
+ * - PUSH_CONST `arg`
+ - Push an int const.
+ - ``[...]``
+ - ``[..., arg]``
+ * - JUMP_ABS_IF_TRUE `arg`
+ - Pop; if top of stack was nonzero, jump to ``arg``.
+ - ``[..., x]``
+ - ``[...]``
Programs can be interpreted, disassembled, and compiled to machine code.
diff --git a/gcc/jit/docs/intro/tutorial05.rst b/gcc/jit/docs/intro/tutorial05.rst
index 5f3ed28c333..b977d1ddf59 100644
--- a/gcc/jit/docs/intro/tutorial05.rst
+++ b/gcc/jit/docs/intro/tutorial05.rst
@@ -42,19 +42,30 @@ within the array.
brainf is hard for humans to read, but it's trivial to write a parser for
it, as there is no lexing; just a stream of bytes. The operations are:
-====================== =============================
-Character Meaning
-====================== =============================
-``>`` ``idx += 1``
-``<`` ``idx -= 1``
-``+`` ``data[idx] += 1``
-``-`` ``data[idx] -= 1``
-``.`` ``output (data[idx])``
-``,`` ``data[idx] = input ()``
-``[`` loop until ``data[idx] == 0``
-``]`` end of loop
-Anything else ignored
-====================== =============================
+.. list-table::
+ :header-rows: 1
+
+ * - Character
+ - Meaning
+
+ * - ``>``
+ - ``idx += 1``
+ * - ``<``
+ - ``idx -= 1``
+ * - ``+``
+ - ``data[idx] += 1``
+ * - ``-``
+ - ``data[idx] -= 1``
+ * - ``.``
+ - ``output (data[idx])``
+ * - ``,``
+ - ``data[idx] = input ()``
+ * - ``[``
+ - loop until ``data[idx] == 0``
+ * - ``]``
+ - end of loop
+ * - Anything else
+ - ignored
Unlike the previous example, we'll implement an ahead-of-time compiler,
which reads ``.bf`` scripts and outputs executables (though it would
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index 91b9c2533cf..adcde8d8eb9 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -169,14 +169,20 @@ For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`.
The available kinds of output are:
-============================================== ==============
-Output kind Typical suffix
-============================================== ==============
-:c:macro:`GCC_JIT_OUTPUT_KIND_ASSEMBLER` .s
-:c:macro:`GCC_JIT_OUTPUT_KIND_OBJECT_FILE` .o
-:c:macro:`GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY` .so or .dll
-:c:macro:`GCC_JIT_OUTPUT_KIND_EXECUTABLE` None, or .exe
-============================================== ==============
+.. list-table::
+ :header-rows: 1
+
+ * - Output kind
+ - Typical suffix
+
+ * - :c:macro:`GCC_JIT_OUTPUT_KIND_ASSEMBLER`
+ - .s
+ * - :c:macro:`GCC_JIT_OUTPUT_KIND_OBJECT_FILE`
+ - .o
+ * - :c:macro:`GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY`
+ - .so or .dll
+ * - :c:macro:`GCC_JIT_OUTPUT_KIND_EXECUTABLE`
+ - None, or .exe
.. c:macro:: GCC_JIT_OUTPUT_KIND_ASSEMBLER
diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst
index 00e2ec8cfeb..ff1eec800ce 100644
--- a/gcc/jit/docs/topics/expressions.rst
+++ b/gcc/jit/docs/topics/expressions.rst
@@ -313,14 +313,20 @@ Unary Operations
The available unary operations are:
-========================================== ============
-Unary Operation C equivalent
-========================================== ============
-:c:macro:`GCC_JIT_UNARY_OP_MINUS` `-(EXPR)`
-:c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE` `~(EXPR)`
-:c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE` `!(EXPR)`
-:c:macro:`GCC_JIT_UNARY_OP_ABS` `abs (EXPR)`
-========================================== ============
+.. list-table::
+ :header-rows: 1
+
+ * - Unary Operation
+ - C equivalent
+
+ * - :c:macro:`GCC_JIT_UNARY_OP_MINUS`
+ - `-(EXPR)`
+ * - :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE`
+ - `~(EXPR)`
+ * - :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE`
+ - `!(EXPR)`
+ * - :c:macro:`GCC_JIT_UNARY_OP_ABS`
+ - `abs (EXPR)`
.. c:macro:: GCC_JIT_UNARY_OP_MINUS
@@ -380,22 +386,36 @@ Binary Operations
The available binary operations are:
-======================================== ============
-Binary Operation C equivalent
-======================================== ============
-:c:macro:`GCC_JIT_BINARY_OP_PLUS` `x + y`
-:c:macro:`GCC_JIT_BINARY_OP_MINUS` `x - y`
-:c:macro:`GCC_JIT_BINARY_OP_MULT` `x * y`
-:c:macro:`GCC_JIT_BINARY_OP_DIVIDE` `x / y`
-:c:macro:`GCC_JIT_BINARY_OP_MODULO` `x % y`
-:c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND` `x & y`
-:c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR` `x ^ y`
-:c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR` `x | y`
-:c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND` `x && y`
-:c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR` `x || y`
-:c:macro:`GCC_JIT_BINARY_OP_LSHIFT` `x << y`
-:c:macro:`GCC_JIT_BINARY_OP_RSHIFT` `x >> y`
-======================================== ============
+.. list-table::
+ :header-rows: 1
+
+ * - Binary Operation
+ - C equivalent
+
+ * - :c:macro:`GCC_JIT_BINARY_OP_PLUS`
+ - `x + y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_MINUS`
+ - `x - y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_MULT`
+ - `x * y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_DIVIDE`
+ - `x / y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_MODULO`
+ - `x % y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND`
+ - `x & y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR`
+ - `x ^ y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR`
+ - `x | y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND`
+ - `x && y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR`
+ - `x || y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_LSHIFT`
+ - `x << y`
+ * - :c:macro:`GCC_JIT_BINARY_OP_RSHIFT`
+ - `x >> y`
.. c:macro:: GCC_JIT_BINARY_OP_PLUS
@@ -536,17 +556,24 @@ Comparisons
.. enum:: gcc_jit_comparison
-======================================= ============
-Comparison C equivalent
-======================================= ============
-:c:macro:`GCC_JIT_COMPARISON_EQ` `x == y`
-:c:macro:`GCC_JIT_COMPARISON_NE` `x != y`
-:c:macro:`GCC_JIT_COMPARISON_LT` `x < y`
-:c:macro:`GCC_JIT_COMPARISON_LE` `x <= y`
-:c:macro:`GCC_JIT_COMPARISON_GT` `x > y`
-:c:macro:`GCC_JIT_COMPARISON_GE` `x >= y`
-======================================= ============
-
+.. list-table::
+ :header-rows: 1
+
+ * - Comparison
+ - C equivalent
+
+ * - :c:macro:`GCC_JIT_COMPARISON_EQ`
+ - `x == y`
+ * - :c:macro:`GCC_JIT_COMPARISON_NE`
+ - `x != y`
+ * - :c:macro:`GCC_JIT_COMPARISON_LT`
+ - `x < y`
+ * - :c:macro:`GCC_JIT_COMPARISON_LE`
+ - `x <= y`
+ * - :c:macro:`GCC_JIT_COMPARISON_GT`
+ - `x > y`
+ * - :c:macro:`GCC_JIT_COMPARISON_GE`
+ - `x >= y`
Function calls
**************
diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst
index db7fac6b267..457b3623ec9 100644
--- a/gcc/jit/docs/topics/types.rst
+++ b/gcc/jit/docs/topics/types.rst
@@ -57,45 +57,78 @@ Standard types
Access a specific type. The available types are:
- ========================================== ================================
- `enum gcc_jit_types` value Meaning
- ========================================== ================================
- :c:data:`GCC_JIT_TYPE_VOID` C's ``void`` type.
- :c:data:`GCC_JIT_TYPE_VOID_PTR` C's ``void *``.
- :c:data:`GCC_JIT_TYPE_BOOL` C++'s ``bool`` type; also C99's
- ``_Bool`` type, aka ``bool`` if
- using stdbool.h.
- :c:data:`GCC_JIT_TYPE_CHAR` C's ``char`` (of some signedness)
- :c:data:`GCC_JIT_TYPE_SIGNED_CHAR` C's ``signed char``
- :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR` C's ``unsigned char``
- :c:data:`GCC_JIT_TYPE_SHORT` C's ``short`` (signed)
- :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT` C's ``unsigned short``
- :c:data:`GCC_JIT_TYPE_INT` C's ``int`` (signed)
- :c:data:`GCC_JIT_TYPE_UNSIGNED_INT` C's ``unsigned int``
- :c:data:`GCC_JIT_TYPE_LONG` C's ``long`` (signed)
- :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG` C's ``unsigned long``
- :c:data:`GCC_JIT_TYPE_LONG_LONG` C99's ``long long`` (signed)
- :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG` C99's ``unsigned long long``
- :c:data:`GCC_JIT_TYPE_UINT8_T` C99's ``uint8_t``
- :c:data:`GCC_JIT_TYPE_UINT16_T` C99's ``uint16_t``
- :c:data:`GCC_JIT_TYPE_UINT32_T` C99's ``uint32_t``
- :c:data:`GCC_JIT_TYPE_UINT64_T` C99's ``uint64_t``
- :c:data:`GCC_JIT_TYPE_UINT128_T` C99's ``__uint128_t``
- :c:data:`GCC_JIT_TYPE_INT8_T` C99's ``int8_t``
- :c:data:`GCC_JIT_TYPE_INT16_T` C99's ``int16_t``
- :c:data:`GCC_JIT_TYPE_INT32_T` C99's ``int32_t``
- :c:data:`GCC_JIT_TYPE_INT64_T` C99's ``int64_t``
- :c:data:`GCC_JIT_TYPE_INT128_T` C99's ``__int128_t``
- :c:data:`GCC_JIT_TYPE_FLOAT`
- :c:data:`GCC_JIT_TYPE_DOUBLE`
- :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
- :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR` C type: ``(const char *)``
- :c:data:`GCC_JIT_TYPE_SIZE_T` C's ``size_t`` type
- :c:data:`GCC_JIT_TYPE_FILE_PTR` C type: ``(FILE *)``
- :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT` C99's ``_Complex float``
- :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE` C99's ``_Complex double``
- :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE` C99's ``_Complex long double``
- ========================================== ================================
+ .. list-table::
+ :header-rows: 1
+
+ * - `enum gcc_jit_types` value
+ - Meaning
+
+ * - :c:data:`GCC_JIT_TYPE_VOID`
+ - C's ``void`` type.
+ * - :c:data:`GCC_JIT_TYPE_VOID_PTR`
+ - C's ``void *``.
+ * - :c:data:`GCC_JIT_TYPE_BOOL`
+ - C++'s ``bool`` type; also C99's ``_Bool`` type, aka ``bool`` if using stdbool.h.
+ * - :c:data:`GCC_JIT_TYPE_CHAR`
+ - C's ``char`` (of some signedness)
+ * - :c:data:`GCC_JIT_TYPE_SIGNED_CHAR`
+ - C's ``signed char``
+ * - :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR`
+ - C's ``unsigned char``
+ * - :c:data:`GCC_JIT_TYPE_SHORT`
+ - C's ``short`` (signed)
+ * - :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT`
+ - C's ``unsigned short``
+ * - :c:data:`GCC_JIT_TYPE_INT`
+ - C's ``int`` (signed)
+ * - :c:data:`GCC_JIT_TYPE_UNSIGNED_INT`
+ - C's ``unsigned int``
+ * - :c:data:`GCC_JIT_TYPE_LONG`
+ - C's ``long`` (signed)
+ * - :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG`
+ - C's ``unsigned long``
+ * - :c:data:`GCC_JIT_TYPE_LONG_LONG`
+ - C99's ``long long`` (signed)
+ * - :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG`
+ - C99's ``unsigned long long``
+ * - :c:data:`GCC_JIT_TYPE_UINT8_T`
+ - C99's ``uint8_t``
+ * - :c:data:`GCC_JIT_TYPE_UINT16_T`
+ - C99's ``uint16_t``
+ * - :c:data:`GCC_JIT_TYPE_UINT32_T`
+ - C99's ``uint32_t``
+ * - :c:data:`GCC_JIT_TYPE_UINT64_T`
+ - C99's ``uint64_t``
+ * - :c:data:`GCC_JIT_TYPE_UINT128_T`
+ - C99's ``__uint128_t``
+ * - :c:data:`GCC_JIT_TYPE_INT8_T`
+ - C99's ``int8_t``
+ * - :c:data:`GCC_JIT_TYPE_INT16_T`
+ - C99's ``int16_t``
+ * - :c:data:`GCC_JIT_TYPE_INT32_T`
+ - C99's ``int32_t``
+ * - :c:data:`GCC_JIT_TYPE_INT64_T`
+ - C99's ``int64_t``
+ * - :c:data:`GCC_JIT_TYPE_INT128_T`
+ - C99's ``__int128_t``
+ * - :c:data:`GCC_JIT_TYPE_FLOAT`
+ -
+ * - :c:data:`GCC_JIT_TYPE_DOUBLE`
+ -
+ * - :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
+ -
+ * - :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`
+ - C type: ``(const char *)``
+ * - :c:data:`GCC_JIT_TYPE_SIZE_T`
+ - C's ``size_t`` type
+ * - :c:data:`GCC_JIT_TYPE_FILE_PTR`
+ - C type: ``(FILE *)``
+ * - :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT`
+ - C99's ``_Complex float``
+ * - :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE`
+ - C99's ``_Complex double``
+ * - :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE`
+ - C99's ``_Complex long double``
.. function:: gcc_jit_type *\
gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 5/7] jit,docs: use list-table instead of fixed table
2022-07-25 10:35 ` [PATCH 5/7] jit,docs: use list-table instead of fixed table Martin Liska
@ 2022-07-25 22:40 ` David Malcolm
0 siblings, 0 replies; 20+ messages in thread
From: David Malcolm @ 2022-07-25 22:40 UTC (permalink / raw)
To: Martin Liska, gcc-patches
On Mon, 2022-07-25 at 12:35 +0200, Martin Liska wrote:
> Use rather list-table that is easible to maintainer and one
> does not have to wrap lines. Moreover, it provides great
> attribute :widths: that correctly works (tested for HTML and PDF).
>
> gcc/jit/ChangeLog:
>
> * docs/cp/intro/tutorial04.rst: Use list-table.
> * docs/intro/tutorial04.rst: Likewise.
> * docs/intro/tutorial05.rst: Likewise.
> * docs/topics/compilation.rst: Likewise.
> * docs/topics/expressions.rst: Likewise.
> * docs/topics/types.rst: Likewise.
OK; thanks
Dave
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
` (4 preceding siblings ...)
2022-07-25 10:35 ` [PATCH 5/7] jit,docs: use list-table instead of fixed table Martin Liska
@ 2022-07-25 12:39 ` Martin Liska
2022-07-25 22:41 ` David Malcolm
2022-07-26 4:55 ` [PATCH 7/7] jit,docs: remove :ref:`modindex` Martin Liška
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liska @ 2022-07-25 12:39 UTC (permalink / raw)
To: gcc-patches
gcc/jit/ChangeLog:
* docs/cp/intro/tutorial02.rst: Use :expr:`type *` for pointers to a type
* docs/cp/topics/asm.rst: Likewise.
* docs/cp/topics/contexts.rst: Likewise.
* docs/cp/topics/expressions.rst: Likewise.
* docs/cp/topics/functions.rst: Likewise.
* docs/cp/topics/objects.rst: Likewise.
* docs/intro/tutorial02.rst: Likewise.
* docs/intro/tutorial03.rst: Likewise.
* docs/intro/tutorial04.rst: Likewise.
* docs/intro/tutorial05.rst: Likewise.
* docs/topics/compilation.rst: Likewise.
* docs/topics/contexts.rst: Likewise.
* docs/topics/objects.rst: Likewise.
---
gcc/jit/docs/cp/intro/tutorial02.rst | 4 ++--
gcc/jit/docs/cp/topics/asm.rst | 2 +-
gcc/jit/docs/cp/topics/contexts.rst | 6 +++---
gcc/jit/docs/cp/topics/expressions.rst | 4 ++--
gcc/jit/docs/cp/topics/functions.rst | 2 +-
gcc/jit/docs/cp/topics/objects.rst | 2 +-
gcc/jit/docs/intro/tutorial02.rst | 16 +++++++--------
gcc/jit/docs/intro/tutorial03.rst | 28 +++++++++++++-------------
gcc/jit/docs/intro/tutorial04.rst | 2 +-
gcc/jit/docs/intro/tutorial05.rst | 4 ++--
gcc/jit/docs/topics/compilation.rst | 8 ++++----
gcc/jit/docs/topics/contexts.rst | 6 +++---
gcc/jit/docs/topics/objects.rst | 6 +++---
13 files changed, 45 insertions(+), 45 deletions(-)
diff --git a/gcc/jit/docs/cp/intro/tutorial02.rst b/gcc/jit/docs/cp/intro/tutorial02.rst
index 55675cc7398..9f9a7f3858e 100644
--- a/gcc/jit/docs/cp/intro/tutorial02.rst
+++ b/gcc/jit/docs/cp/intro/tutorial02.rst
@@ -39,7 +39,7 @@ First we need to include the relevant header:
All state associated with compilation is associated with a
:type:`gccjit::context`, which is a thin C++ wrapper around the C API's
-:c:type:`gcc_jit_context *`.
+:c:expr:`gcc_jit_context *`.
Create one using :func:`gccjit::context::acquire`:
@@ -194,7 +194,7 @@ OK, we've populated the context. We can now compile it using
gcc_jit_result *result;
result = ctxt.compile ();
-and get a :c:type:`gcc_jit_result *`.
+and get a :c:expr:`gcc_jit_result *`.
We can now use :c:func:`gcc_jit_result_get_code` to look up a specific
machine code routine within the result, in this case, the function we
diff --git a/gcc/jit/docs/cp/topics/asm.rst b/gcc/jit/docs/cp/topics/asm.rst
index f7e4e952b10..0d63da3d59e 100644
--- a/gcc/jit/docs/cp/topics/asm.rst
+++ b/gcc/jit/docs/cp/topics/asm.rst
@@ -43,7 +43,7 @@ Adding assembler instructions within a function
to outputs.
:class:`gccjit::extended_asm` is a subclass of :class:`gccjit::object`.
- It is a thin wrapper around the C API's :c:type:`gcc_jit_extended_asm *`.
+ It is a thin wrapper around the C API's :c:expr:`gcc_jit_extended_asm *`.
To avoid having an API entrypoint with a very large number of
parameters, an extended ``asm`` statement is made in stages:
diff --git a/gcc/jit/docs/cp/topics/contexts.rst b/gcc/jit/docs/cp/topics/contexts.rst
index f60f2102b3e..2f2456a9c0d 100644
--- a/gcc/jit/docs/cp/topics/contexts.rst
+++ b/gcc/jit/docs/cp/topics/contexts.rst
@@ -29,9 +29,9 @@ compilation.
You can set up options on it, and add types, functions and code.
Invoking :func:`gccjit::context::compile` on it gives you a
-:c:type:`gcc_jit_result *`.
+:c:expr:`gcc_jit_result *`.
-It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`.
+It is a thin wrapper around the C API's :c:expr:`gcc_jit_context *`.
Lifetime-management
-------------------
@@ -48,7 +48,7 @@ cleanup of such objects is done for you when the context is released.
.. function:: void gccjit::context::release ()
This function releases all resources associated with the given context.
- Both the context itself and all of its :c:type:`gccjit::object *`
+ Both the context itself and all of its :expr:`gccjit::object *`
instances are cleaned up. It should be called exactly once on a given
context.
diff --git a/gcc/jit/docs/cp/topics/expressions.rst b/gcc/jit/docs/cp/topics/expressions.rst
index dec5b477811..01eb2898d0d 100644
--- a/gcc/jit/docs/cp/topics/expressions.rst
+++ b/gcc/jit/docs/cp/topics/expressions.rst
@@ -26,7 +26,7 @@ Rvalues
A :class:`gccjit::rvalue` is an expression that can be computed. It is a
subclass of :class:`gccjit::object`, and is a thin wrapper around
-:c:type:`gcc_jit_rvalue *` from the C API.
+:c:expr:`gcc_jit_rvalue *` from the C API.
It can be simple, e.g.:
@@ -491,7 +491,7 @@ a storage area (such as a variable). It is a subclass of
:class:`gccjit::rvalue`, where the rvalue is computed by reading from the
storage area.
-It iss a thin wrapper around :c:type:`gcc_jit_lvalue *` from the C API.
+It iss a thin wrapper around :c:expr:`gcc_jit_lvalue *` from the C API.
.. function:: gccjit::rvalue \
gccjit::lvalue::get_address (gccjit::location loc)
diff --git a/gcc/jit/docs/cp/topics/functions.rst b/gcc/jit/docs/cp/topics/functions.rst
index 4e325ac3fef..24534cc5d4f 100644
--- a/gcc/jit/docs/cp/topics/functions.rst
+++ b/gcc/jit/docs/cp/topics/functions.rst
@@ -36,7 +36,7 @@ Params
:class:`gccjit::param` is a subclass of :class:`gccjit::lvalue` (and thus
of :class:`gccjit::rvalue` and :class:`gccjit::object`). It is a thin
-wrapper around the C API's :c:type:`gcc_jit_param *`.
+wrapper around the C API's :c:expr:`gcc_jit_param *`.
Functions
---------
diff --git a/gcc/jit/docs/cp/topics/objects.rst b/gcc/jit/docs/cp/topics/objects.rst
index d81a84cab40..ca9243b1c71 100644
--- a/gcc/jit/docs/cp/topics/objects.rst
+++ b/gcc/jit/docs/cp/topics/objects.rst
@@ -23,7 +23,7 @@ Objects
.. class:: gccjit::object
Almost every entity in the API (with the exception of
-:class:`gccjit::context` and :c:type:`gcc_jit_result *`) is a
+:class:`gccjit::context` and :c:expr:`gcc_jit_result *`) is a
"contextual" object, a :class:`gccjit::object`.
A JIT object:
diff --git a/gcc/jit/docs/intro/tutorial02.rst b/gcc/jit/docs/intro/tutorial02.rst
index 5739548b0e3..9fcaad5518c 100644
--- a/gcc/jit/docs/intro/tutorial02.rst
+++ b/gcc/jit/docs/intro/tutorial02.rst
@@ -38,7 +38,7 @@ First we need to include the relevant header:
#include <libgccjit.h>
All state associated with compilation is associated with a
-:c:type:`gcc_jit_context *`.
+:c:expr:`gcc_jit_context *`.
Create one using :c:func:`gcc_jit_context_acquire`:
@@ -50,7 +50,7 @@ Create one using :c:func:`gcc_jit_context_acquire`:
The JIT library has a system of types. It is statically-typed: every
expression is of a specific type, fixed at compile-time. In our example,
all of the expressions are of the C `int` type, so let's obtain this from
-the context, as a :c:type:`gcc_jit_type *`, using
+the context, as a :c:expr:`gcc_jit_type *`, using
:c:func:`gcc_jit_context_get_type`:
.. code-block:: c
@@ -58,8 +58,8 @@ the context, as a :c:type:`gcc_jit_type *`, using
gcc_jit_type *int_type =
gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
-:c:type:`gcc_jit_type *` is an example of a "contextual" object: every
-entity in the API is associated with a :c:type:`gcc_jit_context *`.
+:c:expr:`gcc_jit_type *` is an example of a "contextual" object: every
+entity in the API is associated with a :c:expr:`gcc_jit_context *`.
Memory management is easy: all such "contextual" objects are automatically
cleaned up for you when the context is released, using
@@ -93,7 +93,7 @@ For example, :c:func:`gcc_jit_type_as_object`:
gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
-One thing you can do with a :c:type:`gcc_jit_object *` is
+One thing you can do with a :c:expr:`gcc_jit_object *` is
to ask it for a human-readable description, using
:c:func:`gcc_jit_object_get_debug_string`:
@@ -157,8 +157,8 @@ We can build the expression using :c:func:`gcc_jit_context_new_binary_op`:
gcc_jit_param_as_rvalue (param_i),
gcc_jit_param_as_rvalue (param_i));
-A :c:type:`gcc_jit_rvalue *` is another example of a
-:c:type:`gcc_jit_object *` subclass. We can upcast it using
+A :c:expr:`gcc_jit_rvalue *` is another example of a
+:c:expr:`gcc_jit_object *` subclass. We can upcast it using
:c:func:`gcc_jit_rvalue_as_object` and as before print it with
:c:func:`gcc_jit_object_get_debug_string`.
@@ -190,7 +190,7 @@ OK, we've populated the context. We can now compile it using
gcc_jit_result *result;
result = gcc_jit_context_compile (ctxt);
-and get a :c:type:`gcc_jit_result *`.
+and get a :c:expr:`gcc_jit_result *`.
At this point we're done with the context; we can release it:
diff --git a/gcc/jit/docs/intro/tutorial03.rst b/gcc/jit/docs/intro/tutorial03.rst
index 50d71ba6d1a..478ea2721de 100644
--- a/gcc/jit/docs/intro/tutorial03.rst
+++ b/gcc/jit/docs/intro/tutorial03.rst
@@ -55,7 +55,7 @@ Here's what the final control flow graph will look like:
:alt: image of a control flow graph
As before, we include the libgccjit header and make a
-:c:type:`gcc_jit_context *`.
+:c:expr:`gcc_jit_context *`.
.. code-block:: c
@@ -98,14 +98,14 @@ Let's build the function:
Expressions: lvalues and rvalues
********************************
-The base class of expression is the :c:type:`gcc_jit_rvalue *`,
+The base class of expression is the :c:expr:`gcc_jit_rvalue *`,
representing an expression that can be on the *right*-hand side of
an assignment: a value that can be computed somehow, and assigned
*to* a storage area (such as a variable). It has a specific
-:c:type:`gcc_jit_type *`.
+:c:expr:`gcc_jit_type *`.
-Anothe important class is :c:type:`gcc_jit_lvalue *`.
-A :c:type:`gcc_jit_lvalue *`. is something that can of the *left*-hand
+Anothe important class is :c:expr:`gcc_jit_lvalue *`.
+A :c:expr:`gcc_jit_lvalue *`. is something that can of the *left*-hand
side of an assignment: a storage area (such as a variable).
In other words, every assignment can be thought of as:
@@ -114,8 +114,8 @@ In other words, every assignment can be thought of as:
LVALUE = RVALUE;
-Note that :c:type:`gcc_jit_lvalue *` is a subclass of
-:c:type:`gcc_jit_rvalue *`, where in an assignment of the form:
+Note that :c:expr:`gcc_jit_lvalue *` is a subclass of
+:c:expr:`gcc_jit_rvalue *`, where in an assignment of the form:
.. code-block:: c
@@ -135,10 +135,10 @@ So far the only expressions we've seen are `i * i`:
gcc_jit_param_as_rvalue (param_i),
gcc_jit_param_as_rvalue (param_i));
-which is a :c:type:`gcc_jit_rvalue *`, and the various function
+which is a :c:expr:`gcc_jit_rvalue *`, and the various function
parameters: `param_i` and `param_n`, instances of
-:c:type:`gcc_jit_param *`, which is a subclass of
-:c:type:`gcc_jit_lvalue *` (and, in turn, of :c:type:`gcc_jit_rvalue *`):
+:c:expr:`gcc_jit_param *`, which is a subclass of
+:c:expr:`gcc_jit_lvalue *` (and, in turn, of :c:expr:`gcc_jit_rvalue *`):
we can both read from and write to function parameters within the
body of a function.
@@ -154,7 +154,7 @@ name:
gcc_jit_lvalue *sum =
gcc_jit_function_new_local (func, NULL, the_type, "sum");
-These are instances of :c:type:`gcc_jit_lvalue *` - they can be read from
+These are instances of :c:expr:`gcc_jit_lvalue *` - they can be read from
and written to.
Note that there is no precanned way to create *and* initialize a variable
@@ -178,8 +178,8 @@ handle the control flow. In this case, we need 4 blocks:
3. the body of the loop
4. after the loop terminates (`return sum`)
-so we create these as :c:type:`gcc_jit_block *` instances within the
-:c:type:`gcc_jit_function *`:
+so we create these as :c:expr:`gcc_jit_block *` instances within the
+:c:expr:`gcc_jit_function *`:
.. code-block:: c
@@ -224,7 +224,7 @@ We can then terminate the entry block by jumping to the conditional:
The conditional block is equivalent to the line `while (i < n)` from our
C example. It contains a single statement: a conditional, which jumps to
one of two destination blocks depending on a boolean
-:c:type:`gcc_jit_rvalue *`, in this case the comparison of `i` and `n`.
+:c:expr:`gcc_jit_rvalue *`, in this case the comparison of `i` and `n`.
We build the comparison using :c:func:`gcc_jit_context_new_comparison`:
.. code-block:: c
diff --git a/gcc/jit/docs/intro/tutorial04.rst b/gcc/jit/docs/intro/tutorial04.rst
index c2e3fb5c054..a08119f51b1 100644
--- a/gcc/jit/docs/intro/tutorial04.rst
+++ b/gcc/jit/docs/intro/tutorial04.rst
@@ -126,7 +126,7 @@ then directly executed in-process:
:end-before: enum opcode
:language: c
-The lifetime of the code is tied to that of a :c:type:`gcc_jit_result *`.
+The lifetime of the code is tied to that of a :c:expr:`gcc_jit_result *`.
We'll handle this by bundling them up in a structure, so that we can
clean them up together by calling :c:func:`gcc_jit_result_release`:
diff --git a/gcc/jit/docs/intro/tutorial05.rst b/gcc/jit/docs/intro/tutorial05.rst
index b977d1ddf59..1c4774486be 100644
--- a/gcc/jit/docs/intro/tutorial05.rst
+++ b/gcc/jit/docs/intro/tutorial05.rst
@@ -95,7 +95,7 @@ Here's what a simple ``.bf`` script looks like:
Converting a brainf script to libgccjit IR
******************************************
-As before we write simple code to populate a :c:type:`gcc_jit_context *`.
+As before we write simple code to populate a :c:expr:`gcc_jit_context *`.
.. literalinclude:: ../examples/tut05-bf.c
:start-after: #define MAX_OPEN_PARENS 16
@@ -261,7 +261,7 @@ state ``idx`` and ``data_cells``:
Other forms of ahead-of-time-compilation
****************************************
-The above demonstrates compiling a :c:type:`gcc_jit_context *` directly
+The above demonstrates compiling a :c:expr:`gcc_jit_context *` directly
to an executable. It's also possible to compile it to an object file,
and to a dynamic library. See the documentation of
:c:func:`gcc_jit_context_compile_to_file` for more information.
diff --git a/gcc/jit/docs/topics/compilation.rst b/gcc/jit/docs/topics/compilation.rst
index adcde8d8eb9..3dd9bc6f5f7 100644
--- a/gcc/jit/docs/topics/compilation.rst
+++ b/gcc/jit/docs/topics/compilation.rst
@@ -20,7 +20,7 @@
Compiling a context
===================
-Once populated, a :c:type:`gcc_jit_context *` can be compiled to
+Once populated, a :c:expr:`gcc_jit_context *` can be compiled to
machine code, either in-memory via :c:func:`gcc_jit_context_compile` or
to disk via :c:func:`gcc_jit_context_compile_to_file`.
@@ -80,7 +80,7 @@ In-memory compilation
Note that the resulting machine code becomes invalid after
:func:`gcc_jit_result_release` is called on the
- :type:`gcc_jit_result *`; attempting to call it after that may lead
+ :expr:`gcc_jit_result *`; attempting to call it after that may lead
to a segmentation fault.
.. function:: void *\
@@ -125,7 +125,7 @@ In-memory compilation
Note that the resulting address becomes invalid after
:func:`gcc_jit_result_release` is called on the
- :type:`gcc_jit_result *`; attempting to use it after that may lead
+ :expr:`gcc_jit_result *`; attempting to use it after that may lead
to a segmentation fault.
.. function:: void\
@@ -153,7 +153,7 @@ For linking in object files, use :c:func:`gcc_jit_context_add_driver_option`.
enum gcc_jit_output_kind output_kind,\
const char *output_path)
- Compile the :c:type:`gcc_jit_context *` to a file of the given
+ Compile the :c:expr:`gcc_jit_context *` to a file of the given
kind.
:c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index 205b5f3dcf5..f746e2819d2 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -39,14 +39,14 @@ cleanup of such objects is done for you when the context is released.
.. function:: gcc_jit_context *gcc_jit_context_acquire (void)
- This function acquires a new :c:type:`gcc_jit_context *` instance,
+ This function acquires a new :c:expr:`gcc_jit_context *` instance,
which is independent of any others that may be present within this
process.
.. function:: void gcc_jit_context_release (gcc_jit_context *ctxt)
This function releases all resources associated with the given context.
- Both the context itself and all of its :c:type:`gcc_jit_object *`
+ Both the context itself and all of its :c:expr:`gcc_jit_object *`
instances are cleaned up. It should be called exactly once on a given
context.
@@ -89,7 +89,7 @@ cleanup of such objects is done for you when the context is released.
Thread-safety
-------------
-Instances of :c:type:`gcc_jit_context *` created via
+Instances of :c:expr:`gcc_jit_context *` created via
:c:func:`gcc_jit_context_acquire` are independent from each other:
only one thread may use a given context at once, but multiple threads
could each have their own contexts without needing locks.
diff --git a/gcc/jit/docs/topics/objects.rst b/gcc/jit/docs/topics/objects.rst
index cd117e2937e..42f3675cd1a 100644
--- a/gcc/jit/docs/topics/objects.rst
+++ b/gcc/jit/docs/topics/objects.rst
@@ -23,12 +23,12 @@ Objects
.. type:: gcc_jit_object
Almost every entity in the API (with the exception of
-:c:type:`gcc_jit_context *` and :c:type:`gcc_jit_result *`) is a
-"contextual" object, a :c:type:`gcc_jit_object *`
+:c:expr:`gcc_jit_context *` and :c:expr:`gcc_jit_result *`) is a
+"contextual" object, a :c:expr:`gcc_jit_object *`
A JIT object:
- * is associated with a :c:type:`gcc_jit_context *`.
+ * is associated with a :c:expr:`gcc_jit_context *`.
* is automatically cleaned up for you when its context is released so
you don't need to manually track and cleanup all objects, just the
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
2022-07-25 12:39 ` [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type Martin Liska
@ 2022-07-25 22:41 ` David Malcolm
2022-07-26 4:50 ` Martin Liška
0 siblings, 1 reply; 20+ messages in thread
From: David Malcolm @ 2022-07-25 22:41 UTC (permalink / raw)
To: Martin Liska, gcc-patches
On Mon, 2022-07-25 at 14:39 +0200, Martin Liska wrote:
> gcc/jit/ChangeLog:
>
> * docs/cp/intro/tutorial02.rst: Use :expr:`type *` for
> pointers to a type
> * docs/cp/topics/asm.rst: Likewise.
> * docs/cp/topics/contexts.rst: Likewise.
> * docs/cp/topics/expressions.rst: Likewise.
> * docs/cp/topics/functions.rst: Likewise.
> * docs/cp/topics/objects.rst: Likewise.
> * docs/intro/tutorial02.rst: Likewise.
> * docs/intro/tutorial03.rst: Likewise.
> * docs/intro/tutorial04.rst: Likewise.
> * docs/intro/tutorial05.rst: Likewise.
> * docs/topics/compilation.rst: Likewise.
> * docs/topics/contexts.rst: Likewise.
> * docs/topics/objects.rst: Likewise.
As per patch 2/7, what's the motivation for this change? The things
being marked up are types rather than expressions.
Dave
> ---
> gcc/jit/docs/cp/intro/tutorial02.rst | 4 ++--
> gcc/jit/docs/cp/topics/asm.rst | 2 +-
> gcc/jit/docs/cp/topics/contexts.rst | 6 +++---
> gcc/jit/docs/cp/topics/expressions.rst | 4 ++--
> gcc/jit/docs/cp/topics/functions.rst | 2 +-
> gcc/jit/docs/cp/topics/objects.rst | 2 +-
> gcc/jit/docs/intro/tutorial02.rst | 16 +++++++--------
> gcc/jit/docs/intro/tutorial03.rst | 28 +++++++++++++-----------
> --
> gcc/jit/docs/intro/tutorial04.rst | 2 +-
> gcc/jit/docs/intro/tutorial05.rst | 4 ++--
> gcc/jit/docs/topics/compilation.rst | 8 ++++----
> gcc/jit/docs/topics/contexts.rst | 6 +++---
> gcc/jit/docs/topics/objects.rst | 6 +++---
> 13 files changed, 45 insertions(+), 45 deletions(-)
>
> diff --git a/gcc/jit/docs/cp/intro/tutorial02.rst
> b/gcc/jit/docs/cp/intro/tutorial02.rst
> index 55675cc7398..9f9a7f3858e 100644
> --- a/gcc/jit/docs/cp/intro/tutorial02.rst
> +++ b/gcc/jit/docs/cp/intro/tutorial02.rst
> @@ -39,7 +39,7 @@ First we need to include the relevant header:
>
> All state associated with compilation is associated with a
> :type:`gccjit::context`, which is a thin C++ wrapper around the C
> API's
> -:c:type:`gcc_jit_context *`.
> +:c:expr:`gcc_jit_context *`.
>
> Create one using :func:`gccjit::context::acquire`:
>
> @@ -194,7 +194,7 @@ OK, we've populated the context. We can now
> compile it using
> gcc_jit_result *result;
> result = ctxt.compile ();
>
> -and get a :c:type:`gcc_jit_result *`.
> +and get a :c:expr:`gcc_jit_result *`.
>
> We can now use :c:func:`gcc_jit_result_get_code` to look up a
> specific
> machine code routine within the result, in this case, the function
> we
> diff --git a/gcc/jit/docs/cp/topics/asm.rst
> b/gcc/jit/docs/cp/topics/asm.rst
> index f7e4e952b10..0d63da3d59e 100644
> --- a/gcc/jit/docs/cp/topics/asm.rst
> +++ b/gcc/jit/docs/cp/topics/asm.rst
> @@ -43,7 +43,7 @@ Adding assembler instructions within a function
> to outputs.
>
> :class:`gccjit::extended_asm` is a subclass of
> :class:`gccjit::object`.
> - It is a thin wrapper around the C API's
> :c:type:`gcc_jit_extended_asm *`.
> + It is a thin wrapper around the C API's
> :c:expr:`gcc_jit_extended_asm *`.
>
> To avoid having an API entrypoint with a very large number of
> parameters, an extended ``asm`` statement is made in stages:
> diff --git a/gcc/jit/docs/cp/topics/contexts.rst
> b/gcc/jit/docs/cp/topics/contexts.rst
> index f60f2102b3e..2f2456a9c0d 100644
> --- a/gcc/jit/docs/cp/topics/contexts.rst
> +++ b/gcc/jit/docs/cp/topics/contexts.rst
> @@ -29,9 +29,9 @@ compilation.
>
> You can set up options on it, and add types, functions and code.
> Invoking :func:`gccjit::context::compile` on it gives you a
> -:c:type:`gcc_jit_result *`.
> +:c:expr:`gcc_jit_result *`.
>
> -It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`.
> +It is a thin wrapper around the C API's :c:expr:`gcc_jit_context *`.
>
> Lifetime-management
> -------------------
> @@ -48,7 +48,7 @@ cleanup of such objects is done for you when the
> context is released.
> .. function:: void gccjit::context::release ()
>
> This function releases all resources associated with the given
> context.
> - Both the context itself and all of its :c:type:`gccjit::object *`
> + Both the context itself and all of its :expr:`gccjit::object *`
> instances are cleaned up. It should be called exactly once on a
> given
> context.
>
> diff --git a/gcc/jit/docs/cp/topics/expressions.rst
> b/gcc/jit/docs/cp/topics/expressions.rst
> index dec5b477811..01eb2898d0d 100644
> --- a/gcc/jit/docs/cp/topics/expressions.rst
> +++ b/gcc/jit/docs/cp/topics/expressions.rst
> @@ -26,7 +26,7 @@ Rvalues
>
> A :class:`gccjit::rvalue` is an expression that can be computed. It
> is a
> subclass of :class:`gccjit::object`, and is a thin wrapper around
> -:c:type:`gcc_jit_rvalue *` from the C API.
> +:c:expr:`gcc_jit_rvalue *` from the C API.
>
> It can be simple, e.g.:
>
> @@ -491,7 +491,7 @@ a storage area (such as a variable). It is a
> subclass of
> :class:`gccjit::rvalue`, where the rvalue is computed by reading
> from the
> storage area.
>
> -It iss a thin wrapper around :c:type:`gcc_jit_lvalue *` from the C
> API.
> +It iss a thin wrapper around :c:expr:`gcc_jit_lvalue *` from the C
> API.
>
> .. function:: gccjit::rvalue \
> gccjit::lvalue::get_address (gccjit::location loc)
> diff --git a/gcc/jit/docs/cp/topics/functions.rst
> b/gcc/jit/docs/cp/topics/functions.rst
> index 4e325ac3fef..24534cc5d4f 100644
> --- a/gcc/jit/docs/cp/topics/functions.rst
> +++ b/gcc/jit/docs/cp/topics/functions.rst
> @@ -36,7 +36,7 @@ Params
>
> :class:`gccjit::param` is a subclass of :class:`gccjit::lvalue` (and
> thus
> of :class:`gccjit::rvalue` and :class:`gccjit::object`). It is a
> thin
> -wrapper around the C API's :c:type:`gcc_jit_param *`.
> +wrapper around the C API's :c:expr:`gcc_jit_param *`.
>
> Functions
> ---------
> diff --git a/gcc/jit/docs/cp/topics/objects.rst
> b/gcc/jit/docs/cp/topics/objects.rst
> index d81a84cab40..ca9243b1c71 100644
> --- a/gcc/jit/docs/cp/topics/objects.rst
> +++ b/gcc/jit/docs/cp/topics/objects.rst
> @@ -23,7 +23,7 @@ Objects
> .. class:: gccjit::object
>
> Almost every entity in the API (with the exception of
> -:class:`gccjit::context` and :c:type:`gcc_jit_result *`) is a
> +:class:`gccjit::context` and :c:expr:`gcc_jit_result *`) is a
> "contextual" object, a :class:`gccjit::object`.
>
> A JIT object:
> diff --git a/gcc/jit/docs/intro/tutorial02.rst
> b/gcc/jit/docs/intro/tutorial02.rst
> index 5739548b0e3..9fcaad5518c 100644
> --- a/gcc/jit/docs/intro/tutorial02.rst
> +++ b/gcc/jit/docs/intro/tutorial02.rst
> @@ -38,7 +38,7 @@ First we need to include the relevant header:
> #include <libgccjit.h>
>
> All state associated with compilation is associated with a
> -:c:type:`gcc_jit_context *`.
> +:c:expr:`gcc_jit_context *`.
>
> Create one using :c:func:`gcc_jit_context_acquire`:
>
> @@ -50,7 +50,7 @@ Create one using :c:func:`gcc_jit_context_acquire`:
> The JIT library has a system of types. It is statically-typed:
> every
> expression is of a specific type, fixed at compile-time. In our
> example,
> all of the expressions are of the C `int` type, so let's obtain this
> from
> -the context, as a :c:type:`gcc_jit_type *`, using
> +the context, as a :c:expr:`gcc_jit_type *`, using
> :c:func:`gcc_jit_context_get_type`:
>
> .. code-block:: c
> @@ -58,8 +58,8 @@ the context, as a :c:type:`gcc_jit_type *`, using
> gcc_jit_type *int_type =
> gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
>
> -:c:type:`gcc_jit_type *` is an example of a "contextual" object:
> every
> -entity in the API is associated with a :c:type:`gcc_jit_context *`.
> +:c:expr:`gcc_jit_type *` is an example of a "contextual" object:
> every
> +entity in the API is associated with a :c:expr:`gcc_jit_context *`.
>
> Memory management is easy: all such "contextual" objects are
> automatically
> cleaned up for you when the context is released, using
> @@ -93,7 +93,7 @@ For example, :c:func:`gcc_jit_type_as_object`:
>
> gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
>
> -One thing you can do with a :c:type:`gcc_jit_object *` is
> +One thing you can do with a :c:expr:`gcc_jit_object *` is
> to ask it for a human-readable description, using
> :c:func:`gcc_jit_object_get_debug_string`:
>
> @@ -157,8 +157,8 @@ We can build the expression using
> :c:func:`gcc_jit_context_new_binary_op`:
> gcc_jit_param_as_rvalue (param_i),
> gcc_jit_param_as_rvalue (param_i));
>
> -A :c:type:`gcc_jit_rvalue *` is another example of a
> -:c:type:`gcc_jit_object *` subclass. We can upcast it using
> +A :c:expr:`gcc_jit_rvalue *` is another example of a
> +:c:expr:`gcc_jit_object *` subclass. We can upcast it using
> :c:func:`gcc_jit_rvalue_as_object` and as before print it with
> :c:func:`gcc_jit_object_get_debug_string`.
>
> @@ -190,7 +190,7 @@ OK, we've populated the context. We can now
> compile it using
> gcc_jit_result *result;
> result = gcc_jit_context_compile (ctxt);
>
> -and get a :c:type:`gcc_jit_result *`.
> +and get a :c:expr:`gcc_jit_result *`.
>
> At this point we're done with the context; we can release it:
>
> diff --git a/gcc/jit/docs/intro/tutorial03.rst
> b/gcc/jit/docs/intro/tutorial03.rst
> index 50d71ba6d1a..478ea2721de 100644
> --- a/gcc/jit/docs/intro/tutorial03.rst
> +++ b/gcc/jit/docs/intro/tutorial03.rst
> @@ -55,7 +55,7 @@ Here's what the final control flow graph will look
> like:
> :alt: image of a control flow graph
>
> As before, we include the libgccjit header and make a
> -:c:type:`gcc_jit_context *`.
> +:c:expr:`gcc_jit_context *`.
>
> .. code-block:: c
>
> @@ -98,14 +98,14 @@ Let's build the function:
> Expressions: lvalues and rvalues
> ********************************
>
> -The base class of expression is the :c:type:`gcc_jit_rvalue *`,
> +The base class of expression is the :c:expr:`gcc_jit_rvalue *`,
> representing an expression that can be on the *right*-hand side of
> an assignment: a value that can be computed somehow, and assigned
> *to* a storage area (such as a variable). It has a specific
> -:c:type:`gcc_jit_type *`.
> +:c:expr:`gcc_jit_type *`.
>
> -Anothe important class is :c:type:`gcc_jit_lvalue *`.
> -A :c:type:`gcc_jit_lvalue *`. is something that can of the *left*-
> hand
> +Anothe important class is :c:expr:`gcc_jit_lvalue *`.
> +A :c:expr:`gcc_jit_lvalue *`. is something that can of the *left*-
> hand
> side of an assignment: a storage area (such as a variable).
>
> In other words, every assignment can be thought of as:
> @@ -114,8 +114,8 @@ In other words, every assignment can be thought
> of as:
>
> LVALUE = RVALUE;
>
> -Note that :c:type:`gcc_jit_lvalue *` is a subclass of
> -:c:type:`gcc_jit_rvalue *`, where in an assignment of the form:
> +Note that :c:expr:`gcc_jit_lvalue *` is a subclass of
> +:c:expr:`gcc_jit_rvalue *`, where in an assignment of the form:
>
> .. code-block:: c
>
> @@ -135,10 +135,10 @@ So far the only expressions we've seen are `i *
> i`:
> gcc_jit_param_as_rvalue (param_i),
> gcc_jit_param_as_rvalue (param_i));
>
> -which is a :c:type:`gcc_jit_rvalue *`, and the various function
> +which is a :c:expr:`gcc_jit_rvalue *`, and the various function
> parameters: `param_i` and `param_n`, instances of
> -:c:type:`gcc_jit_param *`, which is a subclass of
> -:c:type:`gcc_jit_lvalue *` (and, in turn, of :c:type:`gcc_jit_rvalue
> *`):
> +:c:expr:`gcc_jit_param *`, which is a subclass of
> +:c:expr:`gcc_jit_lvalue *` (and, in turn, of :c:expr:`gcc_jit_rvalue
> *`):
> we can both read from and write to function parameters within the
> body of a function.
>
> @@ -154,7 +154,7 @@ name:
> gcc_jit_lvalue *sum =
> gcc_jit_function_new_local (func, NULL, the_type, "sum");
>
> -These are instances of :c:type:`gcc_jit_lvalue *` - they can be read
> from
> +These are instances of :c:expr:`gcc_jit_lvalue *` - they can be read
> from
> and written to.
>
> Note that there is no precanned way to create *and* initialize a
> variable
> @@ -178,8 +178,8 @@ handle the control flow. In this case, we need 4
> blocks:
> 3. the body of the loop
> 4. after the loop terminates (`return sum`)
>
> -so we create these as :c:type:`gcc_jit_block *` instances within the
> -:c:type:`gcc_jit_function *`:
> +so we create these as :c:expr:`gcc_jit_block *` instances within the
> +:c:expr:`gcc_jit_function *`:
>
> .. code-block:: c
>
> @@ -224,7 +224,7 @@ We can then terminate the entry block by jumping
> to the conditional:
> The conditional block is equivalent to the line `while (i < n)` from
> our
> C example. It contains a single statement: a conditional, which
> jumps to
> one of two destination blocks depending on a boolean
> -:c:type:`gcc_jit_rvalue *`, in this case the comparison of `i` and
> `n`.
> +:c:expr:`gcc_jit_rvalue *`, in this case the comparison of `i` and
> `n`.
> We build the comparison using
> :c:func:`gcc_jit_context_new_comparison`:
>
> .. code-block:: c
> diff --git a/gcc/jit/docs/intro/tutorial04.rst
> b/gcc/jit/docs/intro/tutorial04.rst
> index c2e3fb5c054..a08119f51b1 100644
> --- a/gcc/jit/docs/intro/tutorial04.rst
> +++ b/gcc/jit/docs/intro/tutorial04.rst
> @@ -126,7 +126,7 @@ then directly executed in-process:
> :end-before: enum opcode
> :language: c
>
> -The lifetime of the code is tied to that of a
> :c:type:`gcc_jit_result *`.
> +The lifetime of the code is tied to that of a
> :c:expr:`gcc_jit_result *`.
> We'll handle this by bundling them up in a structure, so that we can
> clean them up together by calling :c:func:`gcc_jit_result_release`:
>
> diff --git a/gcc/jit/docs/intro/tutorial05.rst
> b/gcc/jit/docs/intro/tutorial05.rst
> index b977d1ddf59..1c4774486be 100644
> --- a/gcc/jit/docs/intro/tutorial05.rst
> +++ b/gcc/jit/docs/intro/tutorial05.rst
> @@ -95,7 +95,7 @@ Here's what a simple ``.bf`` script looks like:
> Converting a brainf script to libgccjit IR
> ******************************************
>
> -As before we write simple code to populate a
> :c:type:`gcc_jit_context *`.
> +As before we write simple code to populate a
> :c:expr:`gcc_jit_context *`.
>
> .. literalinclude:: ../examples/tut05-bf.c
> :start-after: #define MAX_OPEN_PARENS 16
> @@ -261,7 +261,7 @@ state ``idx`` and ``data_cells``:
> Other forms of ahead-of-time-compilation
> ****************************************
>
> -The above demonstrates compiling a :c:type:`gcc_jit_context *`
> directly
> +The above demonstrates compiling a :c:expr:`gcc_jit_context *`
> directly
> to an executable. It's also possible to compile it to an object
> file,
> and to a dynamic library. See the documentation of
> :c:func:`gcc_jit_context_compile_to_file` for more information.
> diff --git a/gcc/jit/docs/topics/compilation.rst
> b/gcc/jit/docs/topics/compilation.rst
> index adcde8d8eb9..3dd9bc6f5f7 100644
> --- a/gcc/jit/docs/topics/compilation.rst
> +++ b/gcc/jit/docs/topics/compilation.rst
> @@ -20,7 +20,7 @@
> Compiling a context
> ===================
>
> -Once populated, a :c:type:`gcc_jit_context *` can be compiled to
> +Once populated, a :c:expr:`gcc_jit_context *` can be compiled to
> machine code, either in-memory via :c:func:`gcc_jit_context_compile`
> or
> to disk via :c:func:`gcc_jit_context_compile_to_file`.
>
> @@ -80,7 +80,7 @@ In-memory compilation
>
> Note that the resulting machine code becomes invalid after
> :func:`gcc_jit_result_release` is called on the
> - :type:`gcc_jit_result *`; attempting to call it after that may
> lead
> + :expr:`gcc_jit_result *`; attempting to call it after that may
> lead
> to a segmentation fault.
>
> .. function:: void *\
> @@ -125,7 +125,7 @@ In-memory compilation
>
> Note that the resulting address becomes invalid after
> :func:`gcc_jit_result_release` is called on the
> - :type:`gcc_jit_result *`; attempting to use it after that may
> lead
> + :expr:`gcc_jit_result *`; attempting to use it after that may
> lead
> to a segmentation fault.
>
> .. function:: void\
> @@ -153,7 +153,7 @@ For linking in object files, use
> :c:func:`gcc_jit_context_add_driver_option`.
> enum
> gcc_jit_output_kind output_kind,\
> const char
> *output_path)
>
> - Compile the :c:type:`gcc_jit_context *` to a file of the given
> + Compile the :c:expr:`gcc_jit_context *` to a file of the given
> kind.
>
> :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
> diff --git a/gcc/jit/docs/topics/contexts.rst
> b/gcc/jit/docs/topics/contexts.rst
> index 205b5f3dcf5..f746e2819d2 100644
> --- a/gcc/jit/docs/topics/contexts.rst
> +++ b/gcc/jit/docs/topics/contexts.rst
> @@ -39,14 +39,14 @@ cleanup of such objects is done for you when the
> context is released.
>
> .. function:: gcc_jit_context *gcc_jit_context_acquire (void)
>
> - This function acquires a new :c:type:`gcc_jit_context *` instance,
> + This function acquires a new :c:expr:`gcc_jit_context *` instance,
> which is independent of any others that may be present within this
> process.
>
> .. function:: void gcc_jit_context_release (gcc_jit_context *ctxt)
>
> This function releases all resources associated with the given
> context.
> - Both the context itself and all of its :c:type:`gcc_jit_object *`
> + Both the context itself and all of its :c:expr:`gcc_jit_object *`
> instances are cleaned up. It should be called exactly once on a
> given
> context.
>
> @@ -89,7 +89,7 @@ cleanup of such objects is done for you when the
> context is released.
>
> Thread-safety
> -------------
> -Instances of :c:type:`gcc_jit_context *` created via
> +Instances of :c:expr:`gcc_jit_context *` created via
> :c:func:`gcc_jit_context_acquire` are independent from each other:
> only one thread may use a given context at once, but multiple
> threads
> could each have their own contexts without needing locks.
> diff --git a/gcc/jit/docs/topics/objects.rst
> b/gcc/jit/docs/topics/objects.rst
> index cd117e2937e..42f3675cd1a 100644
> --- a/gcc/jit/docs/topics/objects.rst
> +++ b/gcc/jit/docs/topics/objects.rst
> @@ -23,12 +23,12 @@ Objects
> .. type:: gcc_jit_object
>
> Almost every entity in the API (with the exception of
> -:c:type:`gcc_jit_context *` and :c:type:`gcc_jit_result *`) is a
> -"contextual" object, a :c:type:`gcc_jit_object *`
> +:c:expr:`gcc_jit_context *` and :c:expr:`gcc_jit_result *`) is a
> +"contextual" object, a :c:expr:`gcc_jit_object *`
>
> A JIT object:
>
> - * is associated with a :c:type:`gcc_jit_context *`.
> + * is associated with a :c:expr:`gcc_jit_context *`.
>
> * is automatically cleaned up for you when its context is released
> so
> you don't need to manually track and cleanup all objects, just
> the
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
2022-07-25 22:41 ` David Malcolm
@ 2022-07-26 4:50 ` Martin Liška
2022-07-26 15:43 ` David Malcolm
0 siblings, 1 reply; 20+ messages in thread
From: Martin Liška @ 2022-07-26 4:50 UTC (permalink / raw)
To: David Malcolm, gcc-patches
On 7/26/22 00:41, David Malcolm wrote:
> On Mon, 2022-07-25 at 14:39 +0200, Martin Liska wrote:
>> gcc/jit/ChangeLog:
>>
>> * docs/cp/intro/tutorial02.rst: Use :expr:`type *` for
>> pointers to a type
>> * docs/cp/topics/asm.rst: Likewise.
>> * docs/cp/topics/contexts.rst: Likewise.
>> * docs/cp/topics/expressions.rst: Likewise.
>> * docs/cp/topics/functions.rst: Likewise.
>> * docs/cp/topics/objects.rst: Likewise.
>> * docs/intro/tutorial02.rst: Likewise.
>> * docs/intro/tutorial03.rst: Likewise.
>> * docs/intro/tutorial04.rst: Likewise.
>> * docs/intro/tutorial05.rst: Likewise.
>> * docs/topics/compilation.rst: Likewise.
>> * docs/topics/contexts.rst: Likewise.
>> * docs/topics/objects.rst: Likewise.
>
> As per patch 2/7, what's the motivation for this change? The things
> being marked up are types rather than expressions.
Apparently, one can't reference a type pointer with :type:`type *` as I asked
in: https://github.com/sphinx-doc/sphinx/issues/10704
Fixes the following warnings:
/home/marxin/Programming/gcc/gcc/jit/docs/topics/objects.rst:25: WARNING: Unparseable C cross-reference: 'gcc_jit_context *'
Invalid C declaration: Expected end of definition. [error at 16]
gcc_jit_context *
----------------^
Cheers,
Martin
>
> Dave
>
>> ---
>> gcc/jit/docs/cp/intro/tutorial02.rst | 4 ++--
>> gcc/jit/docs/cp/topics/asm.rst | 2 +-
>> gcc/jit/docs/cp/topics/contexts.rst | 6 +++---
>> gcc/jit/docs/cp/topics/expressions.rst | 4 ++--
>> gcc/jit/docs/cp/topics/functions.rst | 2 +-
>> gcc/jit/docs/cp/topics/objects.rst | 2 +-
>> gcc/jit/docs/intro/tutorial02.rst | 16 +++++++--------
>> gcc/jit/docs/intro/tutorial03.rst | 28 +++++++++++++-----------
>> --
>> gcc/jit/docs/intro/tutorial04.rst | 2 +-
>> gcc/jit/docs/intro/tutorial05.rst | 4 ++--
>> gcc/jit/docs/topics/compilation.rst | 8 ++++----
>> gcc/jit/docs/topics/contexts.rst | 6 +++---
>> gcc/jit/docs/topics/objects.rst | 6 +++---
>> 13 files changed, 45 insertions(+), 45 deletions(-)
>>
>> diff --git a/gcc/jit/docs/cp/intro/tutorial02.rst
>> b/gcc/jit/docs/cp/intro/tutorial02.rst
>> index 55675cc7398..9f9a7f3858e 100644
>> --- a/gcc/jit/docs/cp/intro/tutorial02.rst
>> +++ b/gcc/jit/docs/cp/intro/tutorial02.rst
>> @@ -39,7 +39,7 @@ First we need to include the relevant header:
>>
>> All state associated with compilation is associated with a
>> :type:`gccjit::context`, which is a thin C++ wrapper around the C
>> API's
>> -:c:type:`gcc_jit_context *`.
>> +:c:expr:`gcc_jit_context *`.
>>
>> Create one using :func:`gccjit::context::acquire`:
>>
>> @@ -194,7 +194,7 @@ OK, we've populated the context. We can now
>> compile it using
>> gcc_jit_result *result;
>> result = ctxt.compile ();
>>
>> -and get a :c:type:`gcc_jit_result *`.
>> +and get a :c:expr:`gcc_jit_result *`.
>>
>> We can now use :c:func:`gcc_jit_result_get_code` to look up a
>> specific
>> machine code routine within the result, in this case, the function
>> we
>> diff --git a/gcc/jit/docs/cp/topics/asm.rst
>> b/gcc/jit/docs/cp/topics/asm.rst
>> index f7e4e952b10..0d63da3d59e 100644
>> --- a/gcc/jit/docs/cp/topics/asm.rst
>> +++ b/gcc/jit/docs/cp/topics/asm.rst
>> @@ -43,7 +43,7 @@ Adding assembler instructions within a function
>> to outputs.
>>
>> :class:`gccjit::extended_asm` is a subclass of
>> :class:`gccjit::object`.
>> - It is a thin wrapper around the C API's
>> :c:type:`gcc_jit_extended_asm *`.
>> + It is a thin wrapper around the C API's
>> :c:expr:`gcc_jit_extended_asm *`.
>>
>> To avoid having an API entrypoint with a very large number of
>> parameters, an extended ``asm`` statement is made in stages:
>> diff --git a/gcc/jit/docs/cp/topics/contexts.rst
>> b/gcc/jit/docs/cp/topics/contexts.rst
>> index f60f2102b3e..2f2456a9c0d 100644
>> --- a/gcc/jit/docs/cp/topics/contexts.rst
>> +++ b/gcc/jit/docs/cp/topics/contexts.rst
>> @@ -29,9 +29,9 @@ compilation.
>>
>> You can set up options on it, and add types, functions and code.
>> Invoking :func:`gccjit::context::compile` on it gives you a
>> -:c:type:`gcc_jit_result *`.
>> +:c:expr:`gcc_jit_result *`.
>>
>> -It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`.
>> +It is a thin wrapper around the C API's :c:expr:`gcc_jit_context *`.
>>
>> Lifetime-management
>> -------------------
>> @@ -48,7 +48,7 @@ cleanup of such objects is done for you when the
>> context is released.
>> .. function:: void gccjit::context::release ()
>>
>> This function releases all resources associated with the given
>> context.
>> - Both the context itself and all of its :c:type:`gccjit::object *`
>> + Both the context itself and all of its :expr:`gccjit::object *`
>> instances are cleaned up. It should be called exactly once on a
>> given
>> context.
>>
>> diff --git a/gcc/jit/docs/cp/topics/expressions.rst
>> b/gcc/jit/docs/cp/topics/expressions.rst
>> index dec5b477811..01eb2898d0d 100644
>> --- a/gcc/jit/docs/cp/topics/expressions.rst
>> +++ b/gcc/jit/docs/cp/topics/expressions.rst
>> @@ -26,7 +26,7 @@ Rvalues
>>
>> A :class:`gccjit::rvalue` is an expression that can be computed. It
>> is a
>> subclass of :class:`gccjit::object`, and is a thin wrapper around
>> -:c:type:`gcc_jit_rvalue *` from the C API.
>> +:c:expr:`gcc_jit_rvalue *` from the C API.
>>
>> It can be simple, e.g.:
>>
>> @@ -491,7 +491,7 @@ a storage area (such as a variable). It is a
>> subclass of
>> :class:`gccjit::rvalue`, where the rvalue is computed by reading
>> from the
>> storage area.
>>
>> -It iss a thin wrapper around :c:type:`gcc_jit_lvalue *` from the C
>> API.
>> +It iss a thin wrapper around :c:expr:`gcc_jit_lvalue *` from the C
>> API.
>>
>> .. function:: gccjit::rvalue \
>> gccjit::lvalue::get_address (gccjit::location loc)
>> diff --git a/gcc/jit/docs/cp/topics/functions.rst
>> b/gcc/jit/docs/cp/topics/functions.rst
>> index 4e325ac3fef..24534cc5d4f 100644
>> --- a/gcc/jit/docs/cp/topics/functions.rst
>> +++ b/gcc/jit/docs/cp/topics/functions.rst
>> @@ -36,7 +36,7 @@ Params
>>
>> :class:`gccjit::param` is a subclass of :class:`gccjit::lvalue` (and
>> thus
>> of :class:`gccjit::rvalue` and :class:`gccjit::object`). It is a
>> thin
>> -wrapper around the C API's :c:type:`gcc_jit_param *`.
>> +wrapper around the C API's :c:expr:`gcc_jit_param *`.
>>
>> Functions
>> ---------
>> diff --git a/gcc/jit/docs/cp/topics/objects.rst
>> b/gcc/jit/docs/cp/topics/objects.rst
>> index d81a84cab40..ca9243b1c71 100644
>> --- a/gcc/jit/docs/cp/topics/objects.rst
>> +++ b/gcc/jit/docs/cp/topics/objects.rst
>> @@ -23,7 +23,7 @@ Objects
>> .. class:: gccjit::object
>>
>> Almost every entity in the API (with the exception of
>> -:class:`gccjit::context` and :c:type:`gcc_jit_result *`) is a
>> +:class:`gccjit::context` and :c:expr:`gcc_jit_result *`) is a
>> "contextual" object, a :class:`gccjit::object`.
>>
>> A JIT object:
>> diff --git a/gcc/jit/docs/intro/tutorial02.rst
>> b/gcc/jit/docs/intro/tutorial02.rst
>> index 5739548b0e3..9fcaad5518c 100644
>> --- a/gcc/jit/docs/intro/tutorial02.rst
>> +++ b/gcc/jit/docs/intro/tutorial02.rst
>> @@ -38,7 +38,7 @@ First we need to include the relevant header:
>> #include <libgccjit.h>
>>
>> All state associated with compilation is associated with a
>> -:c:type:`gcc_jit_context *`.
>> +:c:expr:`gcc_jit_context *`.
>>
>> Create one using :c:func:`gcc_jit_context_acquire`:
>>
>> @@ -50,7 +50,7 @@ Create one using :c:func:`gcc_jit_context_acquire`:
>> The JIT library has a system of types. It is statically-typed:
>> every
>> expression is of a specific type, fixed at compile-time. In our
>> example,
>> all of the expressions are of the C `int` type, so let's obtain this
>> from
>> -the context, as a :c:type:`gcc_jit_type *`, using
>> +the context, as a :c:expr:`gcc_jit_type *`, using
>> :c:func:`gcc_jit_context_get_type`:
>>
>> .. code-block:: c
>> @@ -58,8 +58,8 @@ the context, as a :c:type:`gcc_jit_type *`, using
>> gcc_jit_type *int_type =
>> gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT);
>>
>> -:c:type:`gcc_jit_type *` is an example of a "contextual" object:
>> every
>> -entity in the API is associated with a :c:type:`gcc_jit_context *`.
>> +:c:expr:`gcc_jit_type *` is an example of a "contextual" object:
>> every
>> +entity in the API is associated with a :c:expr:`gcc_jit_context *`.
>>
>> Memory management is easy: all such "contextual" objects are
>> automatically
>> cleaned up for you when the context is released, using
>> @@ -93,7 +93,7 @@ For example, :c:func:`gcc_jit_type_as_object`:
>>
>> gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
>>
>> -One thing you can do with a :c:type:`gcc_jit_object *` is
>> +One thing you can do with a :c:expr:`gcc_jit_object *` is
>> to ask it for a human-readable description, using
>> :c:func:`gcc_jit_object_get_debug_string`:
>>
>> @@ -157,8 +157,8 @@ We can build the expression using
>> :c:func:`gcc_jit_context_new_binary_op`:
>> gcc_jit_param_as_rvalue (param_i),
>> gcc_jit_param_as_rvalue (param_i));
>>
>> -A :c:type:`gcc_jit_rvalue *` is another example of a
>> -:c:type:`gcc_jit_object *` subclass. We can upcast it using
>> +A :c:expr:`gcc_jit_rvalue *` is another example of a
>> +:c:expr:`gcc_jit_object *` subclass. We can upcast it using
>> :c:func:`gcc_jit_rvalue_as_object` and as before print it with
>> :c:func:`gcc_jit_object_get_debug_string`.
>>
>> @@ -190,7 +190,7 @@ OK, we've populated the context. We can now
>> compile it using
>> gcc_jit_result *result;
>> result = gcc_jit_context_compile (ctxt);
>>
>> -and get a :c:type:`gcc_jit_result *`.
>> +and get a :c:expr:`gcc_jit_result *`.
>>
>> At this point we're done with the context; we can release it:
>>
>> diff --git a/gcc/jit/docs/intro/tutorial03.rst
>> b/gcc/jit/docs/intro/tutorial03.rst
>> index 50d71ba6d1a..478ea2721de 100644
>> --- a/gcc/jit/docs/intro/tutorial03.rst
>> +++ b/gcc/jit/docs/intro/tutorial03.rst
>> @@ -55,7 +55,7 @@ Here's what the final control flow graph will look
>> like:
>> :alt: image of a control flow graph
>>
>> As before, we include the libgccjit header and make a
>> -:c:type:`gcc_jit_context *`.
>> +:c:expr:`gcc_jit_context *`.
>>
>> .. code-block:: c
>>
>> @@ -98,14 +98,14 @@ Let's build the function:
>> Expressions: lvalues and rvalues
>> ********************************
>>
>> -The base class of expression is the :c:type:`gcc_jit_rvalue *`,
>> +The base class of expression is the :c:expr:`gcc_jit_rvalue *`,
>> representing an expression that can be on the *right*-hand side of
>> an assignment: a value that can be computed somehow, and assigned
>> *to* a storage area (such as a variable). It has a specific
>> -:c:type:`gcc_jit_type *`.
>> +:c:expr:`gcc_jit_type *`.
>>
>> -Anothe important class is :c:type:`gcc_jit_lvalue *`.
>> -A :c:type:`gcc_jit_lvalue *`. is something that can of the *left*-
>> hand
>> +Anothe important class is :c:expr:`gcc_jit_lvalue *`.
>> +A :c:expr:`gcc_jit_lvalue *`. is something that can of the *left*-
>> hand
>> side of an assignment: a storage area (such as a variable).
>>
>> In other words, every assignment can be thought of as:
>> @@ -114,8 +114,8 @@ In other words, every assignment can be thought
>> of as:
>>
>> LVALUE = RVALUE;
>>
>> -Note that :c:type:`gcc_jit_lvalue *` is a subclass of
>> -:c:type:`gcc_jit_rvalue *`, where in an assignment of the form:
>> +Note that :c:expr:`gcc_jit_lvalue *` is a subclass of
>> +:c:expr:`gcc_jit_rvalue *`, where in an assignment of the form:
>>
>> .. code-block:: c
>>
>> @@ -135,10 +135,10 @@ So far the only expressions we've seen are `i *
>> i`:
>> gcc_jit_param_as_rvalue (param_i),
>> gcc_jit_param_as_rvalue (param_i));
>>
>> -which is a :c:type:`gcc_jit_rvalue *`, and the various function
>> +which is a :c:expr:`gcc_jit_rvalue *`, and the various function
>> parameters: `param_i` and `param_n`, instances of
>> -:c:type:`gcc_jit_param *`, which is a subclass of
>> -:c:type:`gcc_jit_lvalue *` (and, in turn, of :c:type:`gcc_jit_rvalue
>> *`):
>> +:c:expr:`gcc_jit_param *`, which is a subclass of
>> +:c:expr:`gcc_jit_lvalue *` (and, in turn, of :c:expr:`gcc_jit_rvalue
>> *`):
>> we can both read from and write to function parameters within the
>> body of a function.
>>
>> @@ -154,7 +154,7 @@ name:
>> gcc_jit_lvalue *sum =
>> gcc_jit_function_new_local (func, NULL, the_type, "sum");
>>
>> -These are instances of :c:type:`gcc_jit_lvalue *` - they can be read
>> from
>> +These are instances of :c:expr:`gcc_jit_lvalue *` - they can be read
>> from
>> and written to.
>>
>> Note that there is no precanned way to create *and* initialize a
>> variable
>> @@ -178,8 +178,8 @@ handle the control flow. In this case, we need 4
>> blocks:
>> 3. the body of the loop
>> 4. after the loop terminates (`return sum`)
>>
>> -so we create these as :c:type:`gcc_jit_block *` instances within the
>> -:c:type:`gcc_jit_function *`:
>> +so we create these as :c:expr:`gcc_jit_block *` instances within the
>> +:c:expr:`gcc_jit_function *`:
>>
>> .. code-block:: c
>>
>> @@ -224,7 +224,7 @@ We can then terminate the entry block by jumping
>> to the conditional:
>> The conditional block is equivalent to the line `while (i < n)` from
>> our
>> C example. It contains a single statement: a conditional, which
>> jumps to
>> one of two destination blocks depending on a boolean
>> -:c:type:`gcc_jit_rvalue *`, in this case the comparison of `i` and
>> `n`.
>> +:c:expr:`gcc_jit_rvalue *`, in this case the comparison of `i` and
>> `n`.
>> We build the comparison using
>> :c:func:`gcc_jit_context_new_comparison`:
>>
>> .. code-block:: c
>> diff --git a/gcc/jit/docs/intro/tutorial04.rst
>> b/gcc/jit/docs/intro/tutorial04.rst
>> index c2e3fb5c054..a08119f51b1 100644
>> --- a/gcc/jit/docs/intro/tutorial04.rst
>> +++ b/gcc/jit/docs/intro/tutorial04.rst
>> @@ -126,7 +126,7 @@ then directly executed in-process:
>> :end-before: enum opcode
>> :language: c
>>
>> -The lifetime of the code is tied to that of a
>> :c:type:`gcc_jit_result *`.
>> +The lifetime of the code is tied to that of a
>> :c:expr:`gcc_jit_result *`.
>> We'll handle this by bundling them up in a structure, so that we can
>> clean them up together by calling :c:func:`gcc_jit_result_release`:
>>
>> diff --git a/gcc/jit/docs/intro/tutorial05.rst
>> b/gcc/jit/docs/intro/tutorial05.rst
>> index b977d1ddf59..1c4774486be 100644
>> --- a/gcc/jit/docs/intro/tutorial05.rst
>> +++ b/gcc/jit/docs/intro/tutorial05.rst
>> @@ -95,7 +95,7 @@ Here's what a simple ``.bf`` script looks like:
>> Converting a brainf script to libgccjit IR
>> ******************************************
>>
>> -As before we write simple code to populate a
>> :c:type:`gcc_jit_context *`.
>> +As before we write simple code to populate a
>> :c:expr:`gcc_jit_context *`.
>>
>> .. literalinclude:: ../examples/tut05-bf.c
>> :start-after: #define MAX_OPEN_PARENS 16
>> @@ -261,7 +261,7 @@ state ``idx`` and ``data_cells``:
>> Other forms of ahead-of-time-compilation
>> ****************************************
>>
>> -The above demonstrates compiling a :c:type:`gcc_jit_context *`
>> directly
>> +The above demonstrates compiling a :c:expr:`gcc_jit_context *`
>> directly
>> to an executable. It's also possible to compile it to an object
>> file,
>> and to a dynamic library. See the documentation of
>> :c:func:`gcc_jit_context_compile_to_file` for more information.
>> diff --git a/gcc/jit/docs/topics/compilation.rst
>> b/gcc/jit/docs/topics/compilation.rst
>> index adcde8d8eb9..3dd9bc6f5f7 100644
>> --- a/gcc/jit/docs/topics/compilation.rst
>> +++ b/gcc/jit/docs/topics/compilation.rst
>> @@ -20,7 +20,7 @@
>> Compiling a context
>> ===================
>>
>> -Once populated, a :c:type:`gcc_jit_context *` can be compiled to
>> +Once populated, a :c:expr:`gcc_jit_context *` can be compiled to
>> machine code, either in-memory via :c:func:`gcc_jit_context_compile`
>> or
>> to disk via :c:func:`gcc_jit_context_compile_to_file`.
>>
>> @@ -80,7 +80,7 @@ In-memory compilation
>>
>> Note that the resulting machine code becomes invalid after
>> :func:`gcc_jit_result_release` is called on the
>> - :type:`gcc_jit_result *`; attempting to call it after that may
>> lead
>> + :expr:`gcc_jit_result *`; attempting to call it after that may
>> lead
>> to a segmentation fault.
>>
>> .. function:: void *\
>> @@ -125,7 +125,7 @@ In-memory compilation
>>
>> Note that the resulting address becomes invalid after
>> :func:`gcc_jit_result_release` is called on the
>> - :type:`gcc_jit_result *`; attempting to use it after that may
>> lead
>> + :expr:`gcc_jit_result *`; attempting to use it after that may
>> lead
>> to a segmentation fault.
>>
>> .. function:: void\
>> @@ -153,7 +153,7 @@ For linking in object files, use
>> :c:func:`gcc_jit_context_add_driver_option`.
>> enum
>> gcc_jit_output_kind output_kind,\
>> const char
>> *output_path)
>>
>> - Compile the :c:type:`gcc_jit_context *` to a file of the given
>> + Compile the :c:expr:`gcc_jit_context *` to a file of the given
>> kind.
>>
>> :c:func:`gcc_jit_context_compile_to_file` ignores the suffix of
>> diff --git a/gcc/jit/docs/topics/contexts.rst
>> b/gcc/jit/docs/topics/contexts.rst
>> index 205b5f3dcf5..f746e2819d2 100644
>> --- a/gcc/jit/docs/topics/contexts.rst
>> +++ b/gcc/jit/docs/topics/contexts.rst
>> @@ -39,14 +39,14 @@ cleanup of such objects is done for you when the
>> context is released.
>>
>> .. function:: gcc_jit_context *gcc_jit_context_acquire (void)
>>
>> - This function acquires a new :c:type:`gcc_jit_context *` instance,
>> + This function acquires a new :c:expr:`gcc_jit_context *` instance,
>> which is independent of any others that may be present within this
>> process.
>>
>> .. function:: void gcc_jit_context_release (gcc_jit_context *ctxt)
>>
>> This function releases all resources associated with the given
>> context.
>> - Both the context itself and all of its :c:type:`gcc_jit_object *`
>> + Both the context itself and all of its :c:expr:`gcc_jit_object *`
>> instances are cleaned up. It should be called exactly once on a
>> given
>> context.
>>
>> @@ -89,7 +89,7 @@ cleanup of such objects is done for you when the
>> context is released.
>>
>> Thread-safety
>> -------------
>> -Instances of :c:type:`gcc_jit_context *` created via
>> +Instances of :c:expr:`gcc_jit_context *` created via
>> :c:func:`gcc_jit_context_acquire` are independent from each other:
>> only one thread may use a given context at once, but multiple
>> threads
>> could each have their own contexts without needing locks.
>> diff --git a/gcc/jit/docs/topics/objects.rst
>> b/gcc/jit/docs/topics/objects.rst
>> index cd117e2937e..42f3675cd1a 100644
>> --- a/gcc/jit/docs/topics/objects.rst
>> +++ b/gcc/jit/docs/topics/objects.rst
>> @@ -23,12 +23,12 @@ Objects
>> .. type:: gcc_jit_object
>>
>> Almost every entity in the API (with the exception of
>> -:c:type:`gcc_jit_context *` and :c:type:`gcc_jit_result *`) is a
>> -"contextual" object, a :c:type:`gcc_jit_object *`
>> +:c:expr:`gcc_jit_context *` and :c:expr:`gcc_jit_result *`) is a
>> +"contextual" object, a :c:expr:`gcc_jit_object *`
>>
>> A JIT object:
>>
>> - * is associated with a :c:type:`gcc_jit_context *`.
>> + * is associated with a :c:expr:`gcc_jit_context *`.
>>
>> * is automatically cleaned up for you when its context is released
>> so
>> you don't need to manually track and cleanup all objects, just
>> the
>
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
2022-07-26 4:50 ` Martin Liška
@ 2022-07-26 15:43 ` David Malcolm
0 siblings, 0 replies; 20+ messages in thread
From: David Malcolm @ 2022-07-26 15:43 UTC (permalink / raw)
To: Martin Liška, gcc-patches
On Tue, 2022-07-26 at 06:50 +0200, Martin Liška wrote:
> On 7/26/22 00:41, David Malcolm wrote:
> > On Mon, 2022-07-25 at 14:39 +0200, Martin Liska wrote:
> > > gcc/jit/ChangeLog:
> > >
> > > * docs/cp/intro/tutorial02.rst: Use :expr:`type *` for
> > > pointers to a type
> > > * docs/cp/topics/asm.rst: Likewise.
> > > * docs/cp/topics/contexts.rst: Likewise.
> > > * docs/cp/topics/expressions.rst: Likewise.
> > > * docs/cp/topics/functions.rst: Likewise.
> > > * docs/cp/topics/objects.rst: Likewise.
> > > * docs/intro/tutorial02.rst: Likewise.
> > > * docs/intro/tutorial03.rst: Likewise.
> > > * docs/intro/tutorial04.rst: Likewise.
> > > * docs/intro/tutorial05.rst: Likewise.
> > > * docs/topics/compilation.rst: Likewise.
> > > * docs/topics/contexts.rst: Likewise.
> > > * docs/topics/objects.rst: Likewise.
> >
> > As per patch 2/7, what's the motivation for this change? The
> > things
> > being marked up are types rather than expressions.
>
> Apparently, one can't reference a type pointer with :type:`type *` as
> I asked
> in: https://github.com/sphinx-doc/sphinx/issues/10704
Aha; thanks!
The patch is OK.
Dave
^ permalink raw reply [flat|nested] 20+ messages in thread
* [PATCH 7/7] jit,docs: remove :ref:`modindex`
2022-07-25 13:13 [PATCH 0/7] jit,docs: remove warnings and modernize the docs Martin Liska
` (5 preceding siblings ...)
2022-07-25 12:39 ` [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type Martin Liska
@ 2022-07-26 4:55 ` Martin Liška
2022-07-26 15:44 ` David Malcolm
6 siblings, 1 reply; 20+ messages in thread
From: Martin Liška @ 2022-07-26 4:55 UTC (permalink / raw)
To: gcc-patches
gcc/jit/ChangeLog:
* docs/index.rst: Remove reference to module index
as we don't emit any.
---
gcc/jit/docs/index.rst | 1 -
1 file changed, 1 deletion(-)
diff --git a/gcc/jit/docs/index.rst b/gcc/jit/docs/index.rst
index 21c3140e238..0f575966303 100644
--- a/gcc/jit/docs/index.rst
+++ b/gcc/jit/docs/index.rst
@@ -43,5 +43,4 @@ Indices and tables
==================
* :ref:`genindex`
-* :ref:`modindex`
* :ref:`search`
--
2.37.1
^ permalink raw reply [flat|nested] 20+ messages in thread* Re: [PATCH 7/7] jit,docs: remove :ref:`modindex`
2022-07-26 4:55 ` [PATCH 7/7] jit,docs: remove :ref:`modindex` Martin Liška
@ 2022-07-26 15:44 ` David Malcolm
0 siblings, 0 replies; 20+ messages in thread
From: David Malcolm @ 2022-07-26 15:44 UTC (permalink / raw)
To: Martin Liška, gcc-patches
On Tue, 2022-07-26 at 06:55 +0200, Martin Liška wrote:
> gcc/jit/ChangeLog:
>
> * docs/index.rst: Remove reference to module index
> as we don't emit any.
Patch is OK
Thanks
Dave
> ---
> gcc/jit/docs/index.rst | 1 -
> 1 file changed, 1 deletion(-)
>
> diff --git a/gcc/jit/docs/index.rst b/gcc/jit/docs/index.rst
> index 21c3140e238..0f575966303 100644
> --- a/gcc/jit/docs/index.rst
> +++ b/gcc/jit/docs/index.rst
> @@ -43,5 +43,4 @@ Indices and tables
> ==================
>
> * :ref:`genindex`
> -* :ref:`modindex`
> * :ref:`search`
^ permalink raw reply [flat|nested] 20+ messages in thread