Re: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`

[Eduardo Habkost]

On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote:
> 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".

I don't understand why that would be a reason to not use
default-role.  With default-role, we get an error when misusing
`foo`.  Without default-role, misuse won't be detected at all
(except by manual inspection).

-- 
Eduardo