[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax
From: |
Peter Maydell |
Subject: |
Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol` |
Date: |
Mon, 2 Aug 2021 13:14:57 +0100 |
On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> Replace leftover of GTK-Doc #name syntax with `name`, and use
> default-role:: any, so we can add references to other functions,
> types, and macros.
>
> There are 3 cases that required extra care:
> - #TypeInfo.class_init: kernel-doc doesn't generate c:member::
> directives, so references to C struct members are not possible
> yet. This was replaced with `TypeInfo`.class_init.
> - #CPUClass.reset and #DeviceClass.realize: cpu.h and qdev docs are not
> rendered using Sphinx yet, so use ``code`` syntax for those.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
> docs/devel/qom.rst | 25 +++++++++++++------------
> 1 file changed, 13 insertions(+), 12 deletions(-)
>
> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> index e5fe3597cd8..9c1be5d7fc2 100644
> --- a/docs/devel/qom.rst
> +++ b/docs/devel/qom.rst
> @@ -3,6 +3,7 @@ The QEMU Object Model (QOM)
> ===========================
>
> .. highlight:: c
> +.. default-role:: any
>
> The QEMU Object Model provides a framework for registering user creatable
> types and instantiating objects from those types. QOM provides the following
> @@ -42,8 +43,8 @@ features:
>
> type_init(my_device_register_types)
>
> -In the above example, we create a simple type that is described by #TypeInfo.
> -#TypeInfo describes information about the type including what it inherits
> +In the above example, we create a simple type that is described by
> `TypeInfo`.
> +`TypeInfo` describes information about the type including what it inherits
I've just gone through all of docs/ finding the places where we had `foo` and
probably meant ``foo``, so please don't add any new ones. I would suggest
that you either use the ``double-backtick`` syntax to render as fixed-width
font, or use an explicit role tag so readers of the rST source can tell that
that's what you meant to use, ie avoid "default-role".
thanks
-- PMM
- Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`,
Peter Maydell <=