Re: [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
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
Re: [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
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
Re: [PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
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
[PATCH 6/7] jit,docs: use :expr:`type *` for pointers to a type
gcc/jit/ChangeLog: * docs/cp/intro/tutorial02.rst: Use :expr:`type *` for pointers to a type * docs/cp/topics/asm.rst: Likewise. * docs/cp/topics/contexts.rst: Likewise. * docs/cp/topics/expressions.rst: Likewise. * docs/cp/topics/functions.rst: Likewise. * docs/cp/topics/objects.rst: Likewise. * docs/intro/tutorial02.rst: Likewise. * docs/intro/tutorial03.rst: Likewise. * docs/intro/tutorial04.rst: Likewise. * docs/intro/tutorial05.rst: Likewise. * docs/topics/compilation.rst: Likewise. * docs/topics/contexts.rst: Likewise. * docs/topics/objects.rst: Likewise. --- gcc/jit/docs/cp/intro/tutorial02.rst | 4 ++-- gcc/jit/docs/cp/topics/asm.rst | 2 +- gcc/jit/docs/cp/topics/contexts.rst| 6 +++--- gcc/jit/docs/cp/topics/expressions.rst | 4 ++-- gcc/jit/docs/cp/topics/functions.rst | 2 +- gcc/jit/docs/cp/topics/objects.rst | 2 +- gcc/jit/docs/intro/tutorial02.rst | 16 +++ gcc/jit/docs/intro/tutorial03.rst | 28 +- gcc/jit/docs/intro/tutorial04.rst | 2 +- gcc/jit/docs/intro/tutorial05.rst | 4 ++-- gcc/jit/docs/topics/compilation.rst| 8 gcc/jit/docs/topics/contexts.rst | 6 +++--- gcc/jit/docs/topics/objects.rst| 6 +++--- 13 files changed, 45 insertions(+), 45 deletions(-) diff --git a/gcc/jit/docs/cp/intro/tutorial02.rst b/gcc/jit/docs/cp/intro/tutorial02.rst index 55675cc7398..9f9a7f3858e 100644 --- a/gcc/jit/docs/cp/intro/tutorial02.rst +++ b/gcc/jit/docs/cp/intro/tutorial02.rst @@ -39,7 +39,7 @@ First we need to include the relevant header: All state associated with compilation is associated with a :type:`gccjit::context`, which is a thin C++ wrapper around the C API's -:c:type:`gcc_jit_context *`. +:c:expr:`gcc_jit_context *`. Create one using :func:`gccjit::context::acquire`: @@ -194,7 +194,7 @@ OK, we've populated the context. We can now compile it using gcc_jit_result *result; result = ctxt.compile (); -and get a :c:type:`gcc_jit_result *`. +and get a :c:expr:`gcc_jit_result *`. We can now use :c:func:`gcc_jit_result_get_code` to look up a specific machine code routine within the result, in this case, the function we diff --git a/gcc/jit/docs/cp/topics/asm.rst b/gcc/jit/docs/cp/topics/asm.rst index f7e4e952b10..0d63da3d59e 100644 --- a/gcc/jit/docs/cp/topics/asm.rst +++ b/gcc/jit/docs/cp/topics/asm.rst @@ -43,7 +43,7 @@ Adding assembler instructions within a function to outputs. :class:`gccjit::extended_asm` is a subclass of :class:`gccjit::object`. - It is a thin wrapper around the C API's :c:type:`gcc_jit_extended_asm *`. + It is a thin wrapper around the C API's :c:expr:`gcc_jit_extended_asm *`. To avoid having an API entrypoint with a very large number of parameters, an extended ``asm`` statement is made in stages: diff --git a/gcc/jit/docs/cp/topics/contexts.rst b/gcc/jit/docs/cp/topics/contexts.rst index f60f2102b3e..2f2456a9c0d 100644 --- a/gcc/jit/docs/cp/topics/contexts.rst +++ b/gcc/jit/docs/cp/topics/contexts.rst @@ -29,9 +29,9 @@ compilation. You can set up options on it, and add types, functions and code. Invoking :func:`gccjit::context::compile` on it gives you a -:c:type:`gcc_jit_result *`. +:c:expr:`gcc_jit_result *`. -It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`. +It is a thin wrapper around the C API's :c:expr:`gcc_jit_context *`. Lifetime-management --- @@ -48,7 +48,7 @@ cleanup of such objects is done for you when the context is released. .. function:: void gccjit::context::release () This function releases all resources associated with the given context. - Both the context itself and all of its :c:type:`gccjit::object *` + Both the context itself and all of its :expr:`gccjit::object *` instances are cleaned up. It should be called exactly once on a given context. diff --git a/gcc/jit/docs/cp/topics/expressions.rst b/gcc/jit/docs/cp/topics/expressions.rst index dec5b477811..01eb2898d0d 100644 --- a/gcc/jit/docs/cp/topics/expressions.rst +++ b/gcc/jit/docs/cp/topics/expressions.rst @@ -26,7 +26,7 @@ Rvalues A :class:`gccjit::rvalue` is an expression that can be computed. It is a subclass of :class:`gccjit::object`, and is a thin wrapper around -:c:type:`gcc_jit_rvalue *` from the C API. +:c:expr:`gcc_jit_rvalue *` from the C API. It can be simple, e.g.: @@ -491,7 +491,7 @@ a storage area (such as a variable). It is a subclass of :class:`gccjit::rvalue`, where the rvalue is computed by reading from the storage area. -It iss a thin wrapper around :c:type:`gcc_jit_lvalue *` from the C API. +It iss a thin wrapper around :c:expr:`gcc_jit_lvalue *` from the C API. .. function:: gccjit::rvalue \ gccjit::lvalue::get_address (gccjit::location loc) diff --git a/gcc/jit/docs/cp/topics/functions.rst
