| Message ID | 10eed23621fedb630b49a9cbe89aeab8aa009ac7.1658754788.git.mliska@suse.cz |
|---|---|
| State | New |
| Headers | show |
| Series | jit,docs: remove warnings and modernize the docs | expand |
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
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 > >
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
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