[6/7] jit,docs: use :expr:`type *` for pointers to a type

Message ID 10eed23621fedb630b49a9cbe89aeab8aa009ac7.1658754788.git.mliska@suse.cz
State New, archived
Headers
Series jit,docs: remove warnings and modernize the docs |

Commit Message

Martin Liška July 25, 2022, 12:39 p.m. UTC
  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(-)
  

Comments

David Malcolm July 25, 2022, 10:41 p.m. UTC | #1
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
  
Martin Liška July 26, 2022, 4:50 a.m. UTC | #2
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
> 
>
  
David Malcolm July 26, 2022, 3:43 p.m. UTC | #3
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
  

Patch

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