On Mon, Aug 02, 2021 at 01:14:57PM +0100, Peter Maydell wrote: > On Thu, 29 Jul 2021 at 19:00, Eduardo Habkost <ehabk...@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 <ehabk...@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
