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

Commit Message

Eduardo Habkost July 29, 2021, 5:55 p.m. UTC

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 <[e-mail]>
---
 docs/devel/qom.rst | 31 +++++++++++++++++++++----------
 1 file changed, 21 insertions(+), 10 deletions(-)

Comments

Peter Maydell Aug. 2, 2021, 12:24 p.m. UTC | #1

On Thu, 29 Jul 2021 at 19:03, Eduardo Habkost <[e-mail]> 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 <[e-mail]>
> ---
>  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 <[e-mail]>

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

Patch

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
 ----------------------