[PATCH for-6.2 00/10] QOM documentation updates

[PATCH for-6.2 00/10] QOM documentation updates

[Eduardo Habkost]

This series includes a few fixes to the QOM documentation, and
add some changes to avoid encouraging people from defining
typecast macros manually.

Eduardo Habkost (10):
  docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
  docs: qom: Use Sphinx cross references more often
  docs: qom: Fix autoptr expansion example
  docs: qom: Fix "API Reference" heading level
  docs: qom: Add subsection headings to declaration/definition macros
    section
  docs: qom: Remove unnecessary class typedefs from example
  docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation
  docs: qom: Show actual typecast functions in examples
  docs: qom: Remove OBJECT_CHECK macro examples
  MAINTAINERS: Add qom.rst to QOM section

 MAINTAINERS        |   1 +
 docs/devel/qom.rst | 147 ++++++++++++++++++++++++++++-----------------
 2 files changed, 94 insertions(+), 54 deletions(-)

-- 
2.31.1

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

[Eduardo Habkost]

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
 from, the instance and class size, and constructor/destructor hooks.
 
 Alternatively several static types could be registered using helper macro
@@ -66,13 +67,13 @@ DEFINE_TYPES()
 
    DEFINE_TYPES(device_types_info)
 
-Every type has an #ObjectClass associated with it.  #ObjectClass derivatives
+Every type has an `ObjectClass` associated with it.  `ObjectClass` derivatives
 are instantiated dynamically but there is only ever one instance for any
-given type.  The #ObjectClass typically holds a table of function pointers
+given type.  The `ObjectClass` typically holds a table of function pointers
 for the virtual methods implemented by this type.
 
-Using object_new(), a new #Object derivative will be instantiated.  You can
-cast an #Object to a subclass (or base-class) type using
+Using object_new(), a new `Object` derivative will be instantiated.  You can
+cast an `Object` to a subclass (or base-class) type using
 object_dynamic_cast().  You typically want to define macro wrappers around
 OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a
 specific type:
@@ -111,7 +112,7 @@ The effect of this is that classes automatically inherit any virtual
 function pointers that the parent class has already initialized.  All
 other fields will be zero filled.
 
-Once all of the parent classes have been initialized, #TypeInfo::class_init
+Once all of the parent classes have been initialized, `TypeInfo`::class_init
 is called to let the class being instantiated provide default initialize for
 its virtual functions.  Here is how the above example might be modified
 to introduce an overridden virtual function:
@@ -135,7 +136,7 @@ to introduce an overridden virtual function:
    };
 
 Introducing new virtual methods requires a class to define its own
-struct and to add a .class_size member to the #TypeInfo.  Each method
+struct and to add a .class_size member to the `TypeInfo`.  Each method
 will also have a wrapper function to call it easily:
 
 .. code-block:: c
@@ -188,12 +189,12 @@ strongly-typed first argument.
 If it does not operate on an object instance, it is dubbed
 *class method*.
 
-Methods cannot be overloaded. That is, the #ObjectClass and method name
+Methods cannot be overloaded. That is, the `ObjectClass` and method name
 uniquely identity the function to be called; the signature does not vary
 except for trailing varargs.
 
 Methods are always *virtual*. Overriding a method in
-#TypeInfo.class_init of a subclass leads to any user of the class obtained
+`TypeInfo`.class_init of a subclass leads to any user of the class obtained
 via OBJECT_GET_CLASS() accessing the overridden function.
 The original function is not automatically invoked. It is the responsibility
 of the overriding class to determine whether and when to invoke the method
@@ -273,8 +274,8 @@ Alternatively, object_class_by_name() can be used to obtain the class and
 its non-overridden methods for a specific type. This would correspond to
 ``MyClass::method(...)`` in C++.
 
-The first example of such a QOM method was #CPUClass.reset,
-another example is #DeviceClass.realize.
+The first example of such a QOM method was ``CPUClass.reset``,
+another example is ``DeviceClass.realize``.
 
 Standard type declaration and definition macros
 ===============================================
-- 
2.31.1

[PATCH for-6.2 02/10] docs: qom: Use Sphinx cross references more often

[Eduardo Habkost]

To make the document easier to navigate, use `reference` syntax
more often when mentioning other types, functions, and macros.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 9c1be5d7fc2..3499a8ca3b6 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -48,7 +48,7 @@ In the above example, we create a simple type that is described by `TypeInfo`.
 from, the instance and class size, and constructor/destructor hooks.
 
 Alternatively several static types could be registered using helper macro
-DEFINE_TYPES()
+`DEFINE_TYPES()`:
 
 .. code-block:: c
 
@@ -72,10 +72,10 @@ are instantiated dynamically but there is only ever one instance for any
 given type.  The `ObjectClass` typically holds a table of function pointers
 for the virtual methods implemented by this type.
 
-Using object_new(), a new `Object` derivative will be instantiated.  You can
+Using `object_new()`, a new `Object` derivative will be instantiated.  You can
 cast an `Object` to a subclass (or base-class) type using
-object_dynamic_cast().  You typically want to define macro wrappers around
-OBJECT_CHECK() and OBJECT_CLASS_CHECK() to make it easier to convert to a
+`object_dynamic_cast()`.  You typically want to define macro wrappers around
+`OBJECT_CHECK()` and `OBJECT_CLASS_CHECK()` to make it easier to convert to a
 specific type:
 
 .. code-block:: c
@@ -195,7 +195,7 @@ except for trailing varargs.
 
 Methods are always *virtual*. Overriding a method in
 `TypeInfo`.class_init of a subclass leads to any user of the class obtained
-via OBJECT_GET_CLASS() accessing the overridden function.
+via `OBJECT_GET_CLASS()` accessing the overridden function.
 The original function is not automatically invoked. It is the responsibility
 of the overriding class to determine whether and when to invoke the method
 being overridden.
@@ -270,7 +270,7 @@ class, which someone might choose to change at some point.
        .class_init = derived_class_init,
    };
 
-Alternatively, object_class_by_name() can be used to obtain the class and
+Alternatively, `object_class_by_name()` can be used to obtain the class and
 its non-overridden methods for a specific type. This would correspond to
 ``MyClass::method(...)`` in C++.
 
@@ -285,9 +285,9 @@ convention. To reduce the amount of boilerplate code that needs to be
 written for a new type there are two sets of macros to generate the
 common parts in a standard format.
 
-A type is declared using the OBJECT_DECLARE macro family. In types
+A type is declared using the ``OBJECT_DECLARE`` macro family. In types
 which do not require any virtual functions in the class, the
-OBJECT_DECLARE_SIMPLE_TYPE macro is suitable, and is commonly placed
+`OBJECT_DECLARE_SIMPLE_TYPE` macro is suitable, and is commonly placed
 in the header file:
 
 .. code-block:: c
@@ -319,12 +319,12 @@ This is equivalent to the following:
 
 The 'struct MyDevice' needs to be declared separately.
 If the type requires virtual functions to be declared in the class
-struct, then the alternative OBJECT_DECLARE_TYPE() macro can be
-used. This does the same as OBJECT_DECLARE_SIMPLE_TYPE(), but without
+struct, then the alternative `OBJECT_DECLARE_TYPE()` macro can be
+used. This does the same as `OBJECT_DECLARE_SIMPLE_TYPE()`, but without
 the 'struct MyDeviceClass' definition.
 
-To implement the type, the OBJECT_DEFINE macro family is available.
-In the simple case the OBJECT_DEFINE_TYPE macro is suitable:
+To implement the type, the ``OBJECT_DEFINE`` macro family is available.
+In the simple case the `OBJECT_DEFINE_TYPE()` macro is suitable:
 
 .. code-block:: c
    :caption: Defining a simple type
@@ -362,7 +362,7 @@ system, and the three standard methods now need to be implemented
 along with any other logic required for the type.
 
 If the type needs to implement one or more interfaces, then the
-OBJECT_DEFINE_TYPE_WITH_INTERFACES() macro can be used instead.
+`OBJECT_DEFINE_TYPE_WITH_INTERFACES()` macro can be used instead.
 This accepts an array of interface type names.
 
 .. code-block:: c
@@ -374,7 +374,7 @@ This accepts an array of interface type names.
                                       { NULL })
 
 If the type is not intended to be instantiated, then then
-the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
+the `OBJECT_DEFINE_ABSTRACT_TYPE()` macro can be used instead:
 
 .. code-block:: c
    :caption: Defining a simple abstract type
-- 
2.31.1

[PATCH for-6.2 03/10] docs: qom: Fix autoptr expansion example

[Eduardo Habkost]

The wrong type name was being used.  The autoptr cleanup function
will be declared for the instance type, not the class type.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 3499a8ca3b6..7ef16d92ca6 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -304,7 +304,7 @@ This is equivalent to the following:
    typedef struct MyDevice MyDevice;
    typedef struct MyDeviceClass MyDeviceClass;
 
-   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
+   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
 
    #define MY_DEVICE_GET_CLASS(void *obj) \
            OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
-- 
2.31.1

[PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level

[Eduardo Habkost]

The API reference section was being rendered as a subsection of
the "Standard type declaration and definition macros" subsection.
Fix that.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 7ef16d92ca6..3f48016aa8f 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -385,6 +385,6 @@ the `OBJECT_DEFINE_ABSTRACT_TYPE()` macro can be used instead:
 
 
 API Reference
--------------
+=============
 
 .. kernel-doc:: include/qom/object.h
-- 
2.31.1

[PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section

[Eduardo Habkost]

Add two new subsection headings to make the separation between
"declaration macros" and "definition macros" more visible.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 3f48016aa8f..05d045bf570 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -285,6 +285,9 @@ convention. To reduce the amount of boilerplate code that needs to be
 written for a new type there are two sets of macros to generate the
 common parts in a standard format.
 
+Type declaration macros
+-----------------------
+
 A type is declared using the ``OBJECT_DECLARE`` macro family. In types
 which do not require any virtual functions in the class, the
 `OBJECT_DECLARE_SIMPLE_TYPE` macro is suitable, and is commonly placed
@@ -323,6 +326,9 @@ struct, then the alternative `OBJECT_DECLARE_TYPE()` macro can be
 used. This does the same as `OBJECT_DECLARE_SIMPLE_TYPE()`, but without
 the 'struct MyDeviceClass' definition.
 
+Type definition macros
+----------------------
+
 To implement the type, the ``OBJECT_DEFINE`` macro family is available.
 In the simple case the `OBJECT_DEFINE_TYPE()` macro is suitable:
 
-- 
2.31.1

[PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Eduardo Habkost]

When there's no specific class struct used for a QOM type, we
normally don't define a typedef for it.  Remove the typedef from
the minimal example, as it is unnecessary.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 05d045bf570..dee60a64c0a 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -20,9 +20,6 @@ features:
 
    #define TYPE_MY_DEVICE "my-device"
 
-   // No new virtual functions: we can reuse the typedef for the
-   // superclass.
-   typedef DeviceClass MyDeviceClass;
    typedef struct MyDevice
    {
        DeviceState parent;
-- 
2.31.1

[PATCH for-6.2 07/10] docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation

[Eduardo Habkost]

The OBJECT_DECLARE_SIMPLE_TYPE documentation was inaccurate: it
doesn't define a class struct or class type checking helpers.

OBJECT_DECLARE_TYPE expansion looks very similar to the existing
example, though.  Rewrite that section to show both both
OBJECT_DECLARE_SIMPLE_TYPE and OBJECT_DECLARE_TYPE.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index dee60a64c0a..aa1f672efbe 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -301,6 +301,27 @@ This is equivalent to the following:
 .. code-block:: c
    :caption: Expansion from declaring a simple type
 
+   typedef struct MyDevice MyDevice;
+   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
+   #define MY_DEVICE(void *obj)
+           OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
+
+The 'struct MyDevice' needs to be declared separately.
+
+If the type requires virtual functions to be declared in a class
+struct, then the alternative `OBJECT_DECLARE_TYPE()` macro can be
+used:
+
+.. code-block:: c
+   :caption: Declaring a type with custom class struct
+
+   OBJECT_DECLARE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+
+This is equivalent to the following:
+
+.. code-block:: c
+   :caption: Expansion from declaring a type with custom class struct
+
    typedef struct MyDevice MyDevice;
    typedef struct MyDeviceClass MyDeviceClass;
 
@@ -313,16 +334,6 @@ This is equivalent to the following:
    #define MY_DEVICE(void *obj)
            OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
 
-   struct MyDeviceClass {
-       DeviceClass parent_class;
-   };
-
-The 'struct MyDevice' needs to be declared separately.
-If the type requires virtual functions to be declared in the class
-struct, then the alternative `OBJECT_DECLARE_TYPE()` macro can be
-used. This does the same as `OBJECT_DECLARE_SIMPLE_TYPE()`, but without
-the 'struct MyDeviceClass' definition.
-
 Type definition macros
 ----------------------
 
-- 
2.31.1

[PATCH for-6.2 08/10] docs: qom: Show actual typecast functions in examples

[Eduardo Habkost]

For clarity and to avoid encouraging people to copy the examples,
show the actual typecast functions being defined by
OBJECT_DECLARE* macros in the examples.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index aa1f672efbe..3ae6f75a1a2 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -303,8 +303,10 @@ This is equivalent to the following:
 
    typedef struct MyDevice MyDevice;
    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
-   #define MY_DEVICE(void *obj)
-           OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
+   static inline MyDevice *MY_DEVICE(void *obj)
+   {
+       return OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE);
+   }
 
 The 'struct MyDevice' needs to be declared separately.
 
@@ -327,12 +329,18 @@ This is equivalent to the following:
 
    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
 
-   #define MY_DEVICE_GET_CLASS(void *obj) \
-           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
-   #define MY_DEVICE_CLASS(void *klass) \
-           OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
-   #define MY_DEVICE(void *obj)
-           OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
+   static inline MyDeviceClass *MY_DEVICE_GET_CLASS(void *obj)
+   {
+       return OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE);
+   }
+   static inline MyDeviceClass *MY_DEVICE_CLASS(void *klass)
+   {
+       return OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE);
+   }
+   static inline MyDevice *MY_DEVICE(void *obj)
+   {
+       return OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE);
+   }
 
 Type definition macros
 ----------------------
-- 
2.31.1

[PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples

[Eduardo Habkost]

We shouldn't encourage people to keep defining typecast macros
manually, when we have the OBJECT_DECLARE* macros.  Remove the
section showing how to define them, and replace with a section
explaining how typecasting works.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qom.rst | 46 +++++++++++++++++++++++++++++++---------------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
index 3ae6f75a1a2..0f222555019 100644
--- a/docs/devel/qom.rst
+++ b/docs/devel/qom.rst
@@ -69,21 +69,10 @@ are instantiated dynamically but there is only ever one instance for any
 given type.  The `ObjectClass` typically holds a table of function pointers
 for the virtual methods implemented by this type.
 
-Using `object_new()`, a new `Object` derivative will be instantiated.  You can
-cast an `Object` to a subclass (or base-class) type using
-`object_dynamic_cast()`.  You typically want to define macro wrappers around
-`OBJECT_CHECK()` and `OBJECT_CLASS_CHECK()` to make it easier to convert to a
-specific type:
-
-.. code-block:: c
-   :caption: Typecasting macros
-
-   #define MY_DEVICE_GET_CLASS(obj) \
-      OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
-   #define MY_DEVICE_CLASS(klass) \
-      OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
-   #define MY_DEVICE(obj) \
-      OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
+Using `object_new()`, a new `Object` derivative will be
+instantiated.  You can cast an `Object` to a subclass (or
+base-class) type using `object_dynamic_cast()` or :ref:`typecast
+wrappers <typecasting>`.
 
 In case the ObjectClass implementation can be built as module a
 module_obj() line must be added to make sure qemu loads the module
@@ -93,6 +82,31 @@ when the object is needed.
 
    module_obj(TYPE_MY_DEVICE);
 
+.. _typecasting:
+
+Typecasting
+===========
+
+The `OBJECT_DECLARE macros <OBJECT_DECLARE>` automatically define
+typecasting functions having signatures like these:
+
+.. code-block:: c
+
+   static inline MyDevice *MY_DEVICE(const void *obj);
+   static inline MyDeviceClass *MY_DEVICE_GET_CLASS(const void *obj);
+   static inline MyDeviceClass *MY_DEVICE_CLASS(const void *klass);
+
+These typecasting functions are wrappers around `OBJECT_CHECK`,
+`OBJECT_GET_CLASS`, and `OBJECT_CLASS_CHECK`.  Example usage:
+
+.. code-block:: c
+
+    Object *obj = object_new("my-device");
+    MyDevice *my_dev = MY_DEVICE(obj);
+    DeviceState *dev = DEVICE(my_dev);
+    MyDeviceClass *mdc = MY_DEVICE_GET_CLASS(my_dev);
+    DeviceClass *dc = DEVICE_CLASS(mdc);
+
 Class Initialization
 ====================
 
@@ -282,6 +296,8 @@ convention. To reduce the amount of boilerplate code that needs to be
 written for a new type there are two sets of macros to generate the
 common parts in a standard format.
 
+.. _OBJECT_DECLARE:
+
 Type declaration macros
 -----------------------
 
-- 
2.31.1

[PATCH for-6.2 10/10] MAINTAINERS: Add qom.rst to QOM section

[Eduardo Habkost]

Add qom.rst to the QOM section of MAINTAINERS.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 MAINTAINERS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 42ac45c3e50..dc3f04242eb 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2651,6 +2651,7 @@ M: Paolo Bonzini <pbonzini@redhat.com>
 R: Daniel P. Berrange <berrange@redhat.com>
 R: Eduardo Habkost <ehabkost@redhat.com>
 S: Supported
+F: docs/devel/qom.rst
 F: docs/qdev-device-use.txt
 F: hw/core/qdev*
 F: hw/core/bus.c
-- 
2.31.1

Re: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Markus Armbruster]

Eduardo Habkost <ehabkost@redhat.com> writes:

> When there's no specific class struct used for a QOM type, we
> normally don't define a typedef for it.  Remove the typedef from
> the minimal example, as it is unnecessary.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 3 ---
>  1 file changed, 3 deletions(-)
>
> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> index 05d045bf570..dee60a64c0a 100644
> --- a/docs/devel/qom.rst
> +++ b/docs/devel/qom.rst
> @@ -20,9 +20,6 @@ features:
>  
>     #define TYPE_MY_DEVICE "my-device"
>  
> -   // No new virtual functions: we can reuse the typedef for the
> -   // superclass.
> -   typedef DeviceClass MyDeviceClass;
>     typedef struct MyDevice
>     {
>         DeviceState parent;

Documenting existing practice makes sense, but I'm not sure the existing
practice to elide this typedef makes sense.

Re: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Peter Maydell]

On Fri, 30 Jul 2021 at 09:18, Markus Armbruster <armbru@redhat.com> wrote:
>
> Eduardo Habkost <ehabkost@redhat.com> writes:
>
> > When there's no specific class struct used for a QOM type, we
> > normally don't define a typedef for it.  Remove the typedef from
> > the minimal example, as it is unnecessary.
> >
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  docs/devel/qom.rst | 3 ---
> >  1 file changed, 3 deletions(-)
> >
> > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > index 05d045bf570..dee60a64c0a 100644
> > --- a/docs/devel/qom.rst
> > +++ b/docs/devel/qom.rst
> > @@ -20,9 +20,6 @@ features:
> >
> >     #define TYPE_MY_DEVICE "my-device"
> >
> > -   // No new virtual functions: we can reuse the typedef for the
> > -   // superclass.
> > -   typedef DeviceClass MyDeviceClass;
> >     typedef struct MyDevice
> >     {
> >         DeviceState parent;
>
> Documenting existing practice makes sense, but I'm not sure the existing
> practice to elide this typedef makes sense.

The QOMConventions page on the wiki
https://wiki.qemu.org/Documentation/QOMConventions
makes what I think is a reasonable distinction:

# If your class (a) will be subclassed or (b) has member fields it needs
# to put in its class struct then you should write all of:
#
# a FOO_CLASS macro
# a FOO_GET_CLASS macro
# a FooClass structure definition containing at least the parent class field
#
# and your TypeInfo for this class should set the .class_size field to
sizeof(FooClass).
#
# These ensure that nothing in future should need changing if new fields are
# added to your class struct, and that any subclasses have the correct typenames
# available so they won't need to change either even if your
implementation changes.
#
# If your class meets neither of the above requirements (ie it is a
simple leaf class) then:
#
# don't provide FOO_CLASS or FOO_GET_CLASS
# don't provide a FooClass structure
# leave the TypeInfo's .class_size field unset.
#
# If a change means a class which didn't provide these macros/types now needs to
# provide them, then your change should add all of them (ie move the class from
# the latter category to the former).

By those principles, we should never do "typedef DeviceClass MyDeviceClass" --
either we have a real MyDeviceClass which contains at least the parent
class field (ie is not a mere typedef), or we don't provide MyDeviceClass
at all.

I would say the rationale for the wiki's distinction is that we don't
want to require unnecessary boilerplate for leaf classes without
methods (which are by far the most common kind of class), but we don't
want a free-for-all regarding how you write things either. So we define
a standard pattern for leaves and a standard pattern for everything else.

-- PMM

Re: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Daniel P. Berrangé]

On Fri, Jul 30, 2021 at 09:43:55AM +0100, Peter Maydell wrote:
> On Fri, 30 Jul 2021 at 09:18, Markus Armbruster <armbru@redhat.com> wrote:
> >
> > Eduardo Habkost <ehabkost@redhat.com> writes:
> >
> > > When there's no specific class struct used for a QOM type, we
> > > normally don't define a typedef for it.  Remove the typedef from
> > > the minimal example, as it is unnecessary.
> > >
> > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > > ---
> > >  docs/devel/qom.rst | 3 ---
> > >  1 file changed, 3 deletions(-)
> > >
> > > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > > index 05d045bf570..dee60a64c0a 100644
> > > --- a/docs/devel/qom.rst
> > > +++ b/docs/devel/qom.rst
> > > @@ -20,9 +20,6 @@ features:
> > >
> > >     #define TYPE_MY_DEVICE "my-device"
> > >
> > > -   // No new virtual functions: we can reuse the typedef for the
> > > -   // superclass.
> > > -   typedef DeviceClass MyDeviceClass;
> > >     typedef struct MyDevice
> > >     {
> > >         DeviceState parent;
> >
> > Documenting existing practice makes sense, but I'm not sure the existing
> > practice to elide this typedef makes sense.
> 
> The QOMConventions page on the wiki
> https://wiki.qemu.org/Documentation/QOMConventions
> makes what I think is a reasonable distinction:
> 
> # If your class (a) will be subclassed or (b) has member fields it needs
> # to put in its class struct then you should write all of:
> #
> # a FOO_CLASS macro
> # a FOO_GET_CLASS macro
> # a FooClass structure definition containing at least the parent class field
> #
> # and your TypeInfo for this class should set the .class_size field to
> sizeof(FooClass).
> #
> # These ensure that nothing in future should need changing if new fields are
> # added to your class struct, and that any subclasses have the correct typenames
> # available so they won't need to change either even if your
> implementation changes.
> #
> # If your class meets neither of the above requirements (ie it is a
> simple leaf class) then:
> #
> # don't provide FOO_CLASS or FOO_GET_CLASS
> # don't provide a FooClass structure
> # leave the TypeInfo's .class_size field unset.
> #
> # If a change means a class which didn't provide these macros/types now needs to
> # provide them, then your change should add all of them (ie move the class from
> # the latter category to the former).
> 
> By those principles, we should never do "typedef DeviceClass MyDeviceClass" --
> either we have a real MyDeviceClass which contains at least the parent
> class field (ie is not a mere typedef), or we don't provide MyDeviceClass
> at all.
> 
> I would say the rationale for the wiki's distinction is that we don't
> want to require unnecessary boilerplate for leaf classes without
> methods (which are by far the most common kind of class), but we don't
> want a free-for-all regarding how you write things either. So we define
> a standard pattern for leaves and a standard pattern for everything else.

Neither the wiki page above nor this part of the docs is really
showing best practice. The best practice is much later in this
doc where it shows the macros that eliminate all of tedious
boilerplate code:

https://qemu-project.gitlab.io/qemu/devel/qom.html#standard-type-declaration-and-definition-macros

Personally I'd suggest we reverse the documentation order, so that the
first thing we tell people about at the simple macros for declaring
types, and strongly recomend that they are used. Only document the
manual boilerplate at the end, merely as reference material, and
recommend against its use.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section

[Philippe Mathieu-Daudé]

On 7/29/21 7:55 PM, Eduardo Habkost wrote:
> Add two new subsection headings to make the separation between
> "declaration macros" and "definition macros" more visible.
> 
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 6 ++++++
>  1 file changed, 6 insertions(+)

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

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

[Peter Maydell]

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 03/10] docs: qom: Fix autoptr expansion example

[Peter Maydell]

On Thu, 29 Jul 2021 at 18:59, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> The wrong type name was being used.  The autoptr cleanup function
> will be declared for the instance type, not the class type.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level

[Peter Maydell]

On Thu, 29 Jul 2021 at 18:58, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> The API reference section was being rendered as a subsection of
> the "Standard type declaration and definition macros" subsection.
> Fix that.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section

[Peter Maydell]

On Thu, 29 Jul 2021 at 19:01, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> Add two new subsection headings to make the separation between
> "declaration macros" and "definition macros" more visible.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 6 ++++++
>  1 file changed, 6 insertions(+)

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Peter Maydell]

On Thu, 29 Jul 2021 at 19:01, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> When there's no specific class struct used for a QOM type, we
> normally don't define a typedef for it.  Remove the typedef from
> the minimal example, as it is unnecessary.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 3 ---
>  1 file changed, 3 deletions(-)
>
> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> index 05d045bf570..dee60a64c0a 100644
> --- a/docs/devel/qom.rst
> +++ b/docs/devel/qom.rst
> @@ -20,9 +20,6 @@ features:
>
>     #define TYPE_MY_DEVICE "my-device"
>
> -   // No new virtual functions: we can reuse the typedef for the
> -   // superclass.
> -   typedef DeviceClass MyDeviceClass;
>     typedef struct MyDevice
>     {
>         DeviceState parent;

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

though I agree with Daniel that in the long-term we should reverse
the structure of the documents so the recommended macros go first
and the behind-the-scenes boilerplate last.

thanks
-- PMM

Re: [PATCH for-6.2 07/10] docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation

[Peter Maydell]

On Thu, 29 Jul 2021 at 19:03, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> The OBJECT_DECLARE_SIMPLE_TYPE documentation was inaccurate: it
> doesn't define a class struct or class type checking helpers.
>
> OBJECT_DECLARE_TYPE expansion looks very similar to the existing
> example, though.  Rewrite that section to show both both
> OBJECT_DECLARE_SIMPLE_TYPE and OBJECT_DECLARE_TYPE.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 31 +++++++++++++++++++++----------
>  1 file changed, 21 insertions(+), 10 deletions(-)
>
> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> index dee60a64c0a..aa1f672efbe 100644
> --- a/docs/devel/qom.rst
> +++ b/docs/devel/qom.rst
> @@ -301,6 +301,27 @@ This is equivalent to the following:
>  .. code-block:: c
>     :caption: Expansion from declaring a simple type
>
> +   typedef struct MyDevice MyDevice;
> +   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
> +   #define MY_DEVICE(void *obj)
> +           OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
>

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

though I note that the macro doesn't actually create a
MY_DEVICE #define any more -- you get a function named MY_DEVICE().
I guess "equivalent to" covers that.

thanks
-- PMM

Re: [PATCH for-6.2 08/10] docs: qom: Show actual typecast functions in examples

[Peter Maydell]

On Thu, 29 Jul 2021 at 19:03, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> For clarity and to avoid encouraging people to copy the examples,
> show the actual typecast functions being defined by
> OBJECT_DECLARE* macros in the examples.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  docs/devel/qom.rst | 24 ++++++++++++++++--------
>  1 file changed, 16 insertions(+), 8 deletions(-)
>
> diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> index aa1f672efbe..3ae6f75a1a2 100644
> --- a/docs/devel/qom.rst
> +++ b/docs/devel/qom.rst
> @@ -303,8 +303,10 @@ This is equivalent to the following:
>
>     typedef struct MyDevice MyDevice;
>     G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
> -   #define MY_DEVICE(void *obj)
> -           OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
> +   static inline MyDevice *MY_DEVICE(void *obj)
> +   {
> +       return OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE);
> +   }
>
>  The 'struct MyDevice' needs to be declared separately.
>
> @@ -327,12 +329,18 @@ This is equivalent to the following:
>
>     G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDevice, object_unref)
>
> -   #define MY_DEVICE_GET_CLASS(void *obj) \
> -           OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE)
> -   #define MY_DEVICE_CLASS(void *klass) \
> -           OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE)
> -   #define MY_DEVICE(void *obj)
> -           OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE)
> +   static inline MyDeviceClass *MY_DEVICE_GET_CLASS(void *obj)
> +   {
> +       return OBJECT_GET_CLASS(MyDeviceClass, obj, TYPE_MY_DEVICE);
> +   }
> +   static inline MyDeviceClass *MY_DEVICE_CLASS(void *klass)
> +   {
> +       return OBJECT_CLASS_CHECK(MyDeviceClass, klass, TYPE_MY_DEVICE);
> +   }
> +   static inline MyDevice *MY_DEVICE(void *obj)
> +   {
> +       return OBJECT_CHECK(MyDevice, obj, TYPE_MY_DEVICE);
> +   }

...aha, you can ignore my remark on the previous patch :-)

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples

[Peter Maydell]

On Thu, 29 Jul 2021 at 19:05, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> We shouldn't encourage people to keep defining typecast macros
> manually, when we have the OBJECT_DECLARE* macros.  Remove the
> section showing how to define them, and replace with a section
> explaining how typecasting works.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>

other than all the `...` (cf patch 1):

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH for-6.2 10/10] MAINTAINERS: Add qom.rst to QOM section

[Peter Maydell]

On Thu, 29 Jul 2021 at 19:05, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> Add qom.rst to the QOM section of MAINTAINERS.
>
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>  MAINTAINERS | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 42ac45c3e50..dc3f04242eb 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2651,6 +2651,7 @@ M: Paolo Bonzini <pbonzini@redhat.com>
>  R: Daniel P. Berrange <berrange@redhat.com>
>  R: Eduardo Habkost <ehabkost@redhat.com>
>  S: Supported
> +F: docs/devel/qom.rst
>  F: docs/qdev-device-use.txt
>  F: hw/core/qdev*
>  F: hw/core/bus.c
> --

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

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

Re: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Eduardo Habkost]

On Mon, Aug 02, 2021 at 01:19:14PM +0100, Peter Maydell wrote:
> On Thu, 29 Jul 2021 at 19:01, Eduardo Habkost <ehabkost@redhat.com> wrote:
> >
> > When there's no specific class struct used for a QOM type, we
> > normally don't define a typedef for it.  Remove the typedef from
> > the minimal example, as it is unnecessary.
> >
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >  docs/devel/qom.rst | 3 ---
> >  1 file changed, 3 deletions(-)
> >
> > diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst
> > index 05d045bf570..dee60a64c0a 100644
> > --- a/docs/devel/qom.rst
> > +++ b/docs/devel/qom.rst
> > @@ -20,9 +20,6 @@ features:
> >
> >     #define TYPE_MY_DEVICE "my-device"
> >
> > -   // No new virtual functions: we can reuse the typedef for the
> > -   // superclass.
> > -   typedef DeviceClass MyDeviceClass;
> >     typedef struct MyDevice
> >     {
> >         DeviceState parent;
> 
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> 
> though I agree with Daniel that in the long-term we should reverse
> the structure of the documents so the recommended macros go first
> and the behind-the-scenes boilerplate last.

I agree 100%, and maybe I will give it a try later.

My immediate goal was to just remove the examples in the docs
where type checking macros were defined manually.  Since we
introduced the new QOM helper macros, the number of OBJECT_CHECK
macros in the QEMU tree almost doubled (from 40 in commit
8110fa1d94f2 to 75 in commit bccabb3a5d60).

-- 
Eduardo

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

[Peter Maydell]

On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> 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:
> > > 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).

Ah, I didn't realize that we got an error if we set the default-role
to 'any'. That certainly makes it nicer than the default default
of 'cite'.

Is there a sensible default-role we can use as the default for the whole manual,
rather than only declaring it in individual .rst files ?  One of the
things I don't
like about the change here is that it means that `thing` in this individual .rst
file is different from `thing` in every other .rst file in our docs.

Ccing John, who I have just remembered wrote something about Sphinx roles
a few months back:
https://lore.kernel.org/qemu-devel/9fe98807-7d68-2c86-163a-af374c789401@redhat.com/

-- PMM

Re: [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example

[Peter Maydell]

On Wed, 4 Aug 2021 at 21:40, Eduardo Habkost <ehabkost@redhat.com> wrote:
>
> On Mon, Aug 02, 2021 at 01:19:14PM +0100, Peter Maydell wrote:
> > On Thu, 29 Jul 2021 at 19:01, Eduardo Habkost <ehabkost@redhat.com> wrote:
> > >
> > > When there's no specific class struct used for a QOM type, we
> > > normally don't define a typedef for it.  Remove the typedef from
> > > the minimal example, as it is unnecessary.

> > Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> >
> > though I agree with Daniel that in the long-term we should reverse
> > the structure of the documents so the recommended macros go first
> > and the behind-the-scenes boilerplate last.
>
> I agree 100%, and maybe I will give it a try later.
>
> My immediate goal was to just remove the examples in the docs
> where type checking macros were defined manually.  Since we
> introduced the new QOM helper macros, the number of OBJECT_CHECK
> macros in the QEMU tree almost doubled (from 40 in commit
> 8110fa1d94f2 to 75 in commit bccabb3a5d60).

Yeah, to be clear, I'm all in favour of changes like this patchset
and don't think we should hold them up because we have a theoretical
larger restructuring of the documentation we might one day (or never)
get round to.

-- PMM

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

[Eduardo Habkost]

On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote:
> On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost <ehabkost@redhat.com> wrote:
> >
> > 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:
> > > > 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).
> 
> Ah, I didn't realize that we got an error if we set the default-role
> to 'any'. That certainly makes it nicer than the default default
> of 'cite'.
> 
> Is there a sensible default-role we can use as the default for the whole manual,
> rather than only declaring it in individual .rst files ?  One of the
> things I don't
> like about the change here is that it means that `thing` in this individual .rst
> file is different from `thing` in every other .rst file in our docs.

I believe "any" would be a very sensible default role for all
documents, but I don't know how to set default-role globally.
I'll try to find out.

-- 
Eduardo

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 3024 bytes --]

On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost <ehabkost@redhat.com> wrote:

> On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote:
> > On Wed, 4 Aug 2021 at 21:31, Eduardo Habkost <ehabkost@redhat.com>
> wrote:
> > >
> > > 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:
> > > > > 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).
> >
> > Ah, I didn't realize that we got an error if we set the default-role
> > to 'any'. That certainly makes it nicer than the default default
> > of 'cite'.
> >
> > Is there a sensible default-role we can use as the default for the whole
> manual,
> > rather than only declaring it in individual .rst files ?  One of the
> > things I don't
> > like about the change here is that it means that `thing` in this
> individual .rst
> > file is different from `thing` in every other .rst file in our docs.
>
> I believe "any" would be a very sensible default role for all
> documents, but I don't know how to set default-role globally.
> I'll try to find out.
>
> --
> Eduardo
>

Oh, I actually fixed that issue I referenced there back in May -- I keep a
patchset up to date whenever I work on modernizing the QAPI python code
that actually DOES switch our default role to "any" ... I updated it just
today, in fact. I will send it to the list if there's an appetite for it
now.

--js

[-- Attachment #2: Type: text/html, Size: 4119 bytes --]

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

[Eduardo Habkost]

On Wed, Aug 04, 2021 at 08:26:10PM -0400, John Snow wrote:
> On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost <ehabkost@redhat.com> wrote:
> 
> > On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote:
> > > Is there a sensible default-role we can use as the default for the whole
> > manual,
> > > rather than only declaring it in individual .rst files ?  One of the
> > > things I don't
> > > like about the change here is that it means that `thing` in this
> > individual .rst
> > > file is different from `thing` in every other .rst file in our docs.
> >
> > I believe "any" would be a very sensible default role for all
> > documents, but I don't know how to set default-role globally.
> > I'll try to find out.
> 
> Oh, I actually fixed that issue I referenced there back in May -- I keep a
> patchset up to date whenever I work on modernizing the QAPI python code
> that actually DOES switch our default role to "any" ... I updated it just
> today, in fact. I will send it to the list if there's an appetite for it
> now.

If you already have a patch that makes it possible to change the
default role to "any" globally, I'd be glad to include it in v2
of this series.

-- 
Eduardo

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

[Eduardo Habkost]

On Thu, Aug 05, 2021 at 12:36:11PM -0400, Eduardo Habkost wrote:
> On Wed, Aug 04, 2021 at 08:26:10PM -0400, John Snow wrote:
> > On Wed, Aug 4, 2021 at 5:00 PM Eduardo Habkost <ehabkost@redhat.com> wrote:
> > 
> > > On Wed, Aug 04, 2021 at 09:42:24PM +0100, Peter Maydell wrote:
> > > > Is there a sensible default-role we can use as the default for the whole
> > > manual,
> > > > rather than only declaring it in individual .rst files ?  One of the
> > > > things I don't
> > > > like about the change here is that it means that `thing` in this
> > > individual .rst
> > > > file is different from `thing` in every other .rst file in our docs.
> > >
> > > I believe "any" would be a very sensible default role for all
> > > documents, but I don't know how to set default-role globally.
> > > I'll try to find out.
> > 
> > Oh, I actually fixed that issue I referenced there back in May -- I keep a
> > patchset up to date whenever I work on modernizing the QAPI python code
> > that actually DOES switch our default role to "any" ... I updated it just
> > today, in fact. I will send it to the list if there's an appetite for it
> > now.
> 
> If you already have a patch that makes it possible to change the
> default role to "any" globally, I'd be glad to include it in v2
> of this series.

John had submitted the patches at:
https://lore.kernel.org/qemu-devel/20210805004837.1775306-1-jsnow@redhat.com/
(Thanks!)

If John's patches are merged, the only change needed in this
series is the removal of the "default-role" line in patch 01/10.

Instead of submitting v2 for a one-line change, I'm hoping I can
just get Reviewed-by lines for this version.  (the reviews can be
conditional on the removal of the "default-role" line in patch
01/10)

-- 
Eduardo