Skip to contentSkip to conversation

qom documentation fixes

PATCH In review Eduardo Habkost 3 participants 12 messages Oct 3, 2020

lore
Share & tools
lore
#0 lore raw

cover qom documentation fixes

A few fixes to the QOM documentation in docs/devel/qom.rst and include/qom/object.h.

Eduardo Habkost (6):
qom: Fix DECLARE_*CHECKER documentation docs/devel/qom: Fix indentation of bulleted list docs/devel/qom: Fix indentation of code blocks docs/devel/qom: Use *emphasis* for emphasis docs/devel/qom: Remove usage of <code> docs/devel/qom: Avoid long lines

 docs/devel/qom.rst   | 91 +++++++++++++++++++++++---------------------
 include/qom/object.h | 16 ++++----
 2 files changed, 55 insertions(+), 52 deletions(-)
Signature · 1 line
2.26.2
#1 lore raw

PATCH 1/6 qom: Fix DECLARE_*CHECKER documentation

Correct copy/paste mistake in the DECLARE_INSTANCE_CHECKER and DECLARE_CLASS_CHECKERS documentation.

---
 include/qom/object.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/qom/object.h +2 -2
index 27aaa67e63f..e738dfc6744 100644
@@ -170,7 +170,7 @@ struct Object
  * Direct usage of this macro should be avoided, and the complete
  * OBJECT_DECLARE_TYPE macro is recommended instead.
  *
- * This macro will provide the three standard type cast functions for a
+ * This macro will provide the the instance type cast functions for a
  * QOM type.
  */
 #define DECLARE_INSTANCE_CHECKER(InstanceType, OBJ_NAME, TYPENAME) \
@@ -187,7 +187,7 @@ struct Object
  * Direct usage of this macro should be avoided, and the complete
  * OBJECT_DECLARE_TYPE macro is recommended instead.
  *
- * This macro will provide the three standard type cast functions for a
+ * This macro will provide the class type cast functions for a
  * QOM type.
  */
 #define DECLARE_CLASS_CHECKERS(ClassType, OBJ_NAME, TYPENAME) \
Signature · 1 line
2.26.2
Reviewed-by on v1 1/6
#2 lore raw

Re: [PATCH 1/6] qom: Fix DECLARE_*CHECKER documentation

Quoted 13 lines · Eduardo Habkost

Correct copy/paste mistake in the DECLARE_INSTANCE_CHECKER and DECLARE_CLASS_CHECKERS documentation.

---
 include/qom/object.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
include/qom/object.h +0 -0
index 27aaa67e63f..e738dfc6744 100644

include/qom/object.h struct Object · line 173

Quoted 5 lines
include/qom/object.h +1 -1
@@ -170,7 +170,7 @@ struct Object
  * Direct usage of this macro should be avoided, and the complete
  * OBJECT_DECLARE_TYPE macro is recommended instead.
  *
- * This macro will provide the three standard type cast functions for a
+ * This macro will provide the the instance type cast functions for a

Using a single "the":

Quoted 13 lines
include/qom/object.h +1 -1
  * QOM type.
  */
 #define DECLARE_INSTANCE_CHECKER(InstanceType, OBJ_NAME, TYPENAME) \
@@ -187,7 +187,7 @@ struct Object
  * Direct usage of this macro should be avoided, and the complete
  * OBJECT_DECLARE_TYPE macro is recommended instead.
  *
- * This macro will provide the three standard type cast functions for a
+ * This macro will provide the class type cast functions for a
  * QOM type.
  */
 #define DECLARE_CLASS_CHECKERS(ClassType, OBJ_NAME, TYPENAME) \
#3 lore raw

PATCH 2/6 docs/devel/qom: Fix indentation of bulleted list

In reply to Eduardo Habkost

The list was incorrectly parsed as a literal block due to indentation.

---
 docs/devel/qom.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
docs/devel/qom.rst +3 -3
index 0b943b2a1a8..c4857d95c8e 100644
@@ -8,9 +8,9 @@ The QEMU Object Model provides a framework for registering user creatable
 types and instantiating objects from those types.  QOM provides the following
 features:
 
- - System for dynamically registering types
- - Support for single-inheritance of types
- - Multiple inheritance of stateless interfaces
+- System for dynamically registering types
+- Support for single-inheritance of types
+- Multiple inheritance of stateless interfaces
 
 .. code-block:: c
    :caption: Creating a minimal type
Signature · 1 line
2.26.2
#4 lore raw

PATCH 3/6 docs/devel/qom: Fix indentation of code blocks

In reply to Eduardo Habkost

Some code blocks had one extra space, fix that.

---
 docs/devel/qom.rst | 76 +++++++++++++++++++++++-----------------------
 1 file changed, 38 insertions(+), 38 deletions(-)
docs/devel/qom.rst +38 -38
index c4857d95c8e..a47e1b9a239 100644
@@ -284,28 +284,28 @@ in the header file:
 .. code-block:: c
    :caption: Declaring a simple type
 
-    OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
 
 This is equivalent to the following:
 
 .. code-block:: c
    :caption: Expansion from declaring a simple type
 
-    typedef struct MyDevice MyDevice;
-    typedef struct MyDeviceClass MyDeviceClass;
+   typedef struct MyDevice MyDevice;
+   typedef struct MyDeviceClass MyDeviceClass;
 
-    G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, object_unref)
+   G_DEFINE_AUTOPTR_CLEANUP_FUNC(MyDeviceClass, 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)
+   #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)
 
-    struct MyDeviceClass {
-        DeviceClass parent_class;
-    };
+   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
@@ -319,33 +319,33 @@ In the simple case the OBJECT_DEFINE_TYPE macro is suitable:
 .. code-block:: c
    :caption: Defining a simple type
 
-    OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DEFINE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
 
 This is equivalent to the following:
 
 .. code-block:: c
    :caption: Expansion from defining a simple type
 
-    static void my_device_finalize(Object *obj);
-    static void my_device_class_init(ObjectClass *oc, void *data);
-    static void my_device_init(Object *obj);
-
-    static const TypeInfo my_device_info = {
-        .parent = TYPE_DEVICE,
-        .name = TYPE_MY_DEVICE,
-        .instance_size = sizeof(MyDevice),
-        .instance_init = my_device_init,
-        .instance_finalize = my_device_finalize,
-        .class_size = sizeof(MyDeviceClass),
-        .class_init = my_device_class_init,
-    };
-
-    static void
-    my_device_register_types(void)
-    {
-        type_register_static(&my_device_info);
-    }
-    type_init(my_device_register_types);
+   static void my_device_finalize(Object *obj);
+   static void my_device_class_init(ObjectClass *oc, void *data);
+   static void my_device_init(Object *obj);
+
+   static const TypeInfo my_device_info = {
+       .parent = TYPE_DEVICE,
+       .name = TYPE_MY_DEVICE,
+       .instance_size = sizeof(MyDevice),
+       .instance_init = my_device_init,
+       .instance_finalize = my_device_finalize,
+       .class_size = sizeof(MyDeviceClass),
+       .class_init = my_device_class_init,
+   };
+
+   static void
+   my_device_register_types(void)
+   {
+       type_register_static(&my_device_info);
+   }
+   type_init(my_device_register_types);
 
 This is sufficient to get the type registered with the type
 system, and the three standard methods now need to be implemented
@@ -358,9 +358,9 @@ This accepts an array of interface type names.
 .. code-block:: c
    :caption: Defining a simple type implementing interfaces
 
-    OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
-                                       MY_DEVICE, DEVICE,
-                                       { TYPE_USER_CREATABLE }, { NULL })
+   OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
+                                      MY_DEVICE, DEVICE,
+                                      { TYPE_USER_CREATABLE }, { NULL })
 
 If the type is not intended to be instantiated, then then
 the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
@@ -368,7 +368,7 @@ the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
 .. code-block:: c
    :caption: Defining a simple abstract type
 
-    OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
 
 
 
Signature · 1 line
2.26.2
#5 lore raw

PATCH 4/6 docs/devel/qom: Use *emphasis* for emphasis

In reply to Eduardo Habkost

<emphasis> is not valid reST syntax.

---
 docs/devel/qom.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
docs/devel/qom.rst +3 -3
index a47e1b9a239..0c610e20d62 100644
@@ -174,17 +174,17 @@ dynamically cast it to an object that implements the interface.
 Methods
 =======
 
-A <emphasis>method</emphasis> is a function within the namespace scope of
+A *method* is a function within the namespace scope of
 a class. It usually operates on the object instance by passing it as a
 strongly-typed first argument.
 If it does not operate on an object instance, it is dubbed
-<emphasis>class method</emphasis>.
+*class method*.
 
 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 <emphasis>virtual</emphasis>. Overriding a method in
+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.
 The original function is not automatically invoked. It is the responsibility
Signature · 1 line
2.26.2
Reviewed-by on v1 4/6
#6 lore raw

Re: [PATCH 4/6] docs/devel/qom: Use *emphasis* for emphasis

Quoted 3 lines · Eduardo Habkost

<emphasis> is not valid reST syntax.

Quoted 30 lines
---
 docs/devel/qom.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
docs/devel/qom.rst +3 -3
index a47e1b9a239..0c610e20d62 100644
@@ -174,17 +174,17 @@ dynamically cast it to an object that implements the interface.
 Methods
 =======
 
-A <emphasis>method</emphasis> is a function within the namespace scope of
+A *method* is a function within the namespace scope of
 a class. It usually operates on the object instance by passing it as a
 strongly-typed first argument.
 If it does not operate on an object instance, it is dubbed
-<emphasis>class method</emphasis>.
+*class method*.
 
 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 <emphasis>virtual</emphasis>. Overriding a method in
+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.
 The original function is not automatically invoked. It is the responsibility
#7 lore raw

PATCH 5/6 docs/devel/qom: Remove usage of <code>

In reply to Eduardo Habkost

<code> is not valid reST syntax.

Function @argument references don't need additional markup, so just remove <code></code>.

Constants were changed to use reST ``code`` syntax

---
 include/qom/object.h | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
include/qom/object.h +6 -6
index e738dfc6744..16c9bcdf3b0 100644
@@ -1256,7 +1256,7 @@ char *object_property_get_str(Object *obj, const char *name,
  * Writes an object's canonical path to a property.
  *
  * If the link property was created with
- * <code>OBJ_PROP_LINK_STRONG</code> bit, the old target object is
+ * ``OBJ_PROP_LINK_STRONG`` bit, the old target object is
  * unreferenced, and a reference is added to the new target object.
  *
  * Returns: %true on success, %false on failure.
@@ -1603,16 +1603,16 @@ void object_property_allow_set_link(const Object *obj, const char *name,
  *
  * Links form the graph in the object model.
  *
- * The <code>@check()</code> callback is invoked when
+ * The @check() callback is invoked when
  * object_property_set_link() is called and can raise an error to prevent the
- * link being set.  If <code>@check</code> is NULL, the property is read-only
+ * link being set.  If @check is NULL, the property is read-only
  * and cannot be set.
  *
  * Ownership of the pointer that @child points to is transferred to the
- * link property.  The reference count for <code>*@child</code> is
+ * link property.  The reference count for *@child is
  * managed by the property from after the function returns till the
  * property is deleted with object_property_del().  If the
- * <code>@flags</code> <code>OBJ_PROP_LINK_STRONG</code> bit is set,
+ * @flags ``OBJ_PROP_LINK_STRONG`` bit is set,
  * the reference count is decremented when the property is deleted or
  * modified.
  *
@@ -1823,7 +1823,7 @@ ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
  * Add an alias for a property on an object.  This function will add a property
  * of the same type as the forwarded property.
  *
- * The caller must ensure that <code>@target_obj</code> stays alive as long as
+ * The caller must ensure that @target_obj stays alive as long as
  * this property exists.  In the case of a child object or an alias on the same
  * object this will be the case.  For aliases to other objects the caller is
  * responsible for taking a reference.
Signature · 1 line
2.26.2
Reviewed-by on v1 5/6
#8 lore raw

Re: [PATCH 5/6] docs/devel/qom: Remove usage of <code>

Quoted 35 lines · Eduardo Habkost

<code> is not valid reST syntax.

Function @argument references don't need additional markup, so just remove <code></code>.

Constants were changed to use reST ``code`` syntax

---
 include/qom/object.h | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
include/qom/object.h +3 -3
index e738dfc6744..16c9bcdf3b0 100644
@@ -1256,7 +1256,7 @@ char *object_property_get_str(Object *obj, const char *name,
  * Writes an object's canonical path to a property.
  *
  * If the link property was created with
- * <code>OBJ_PROP_LINK_STRONG</code> bit, the old target object is
+ * ``OBJ_PROP_LINK_STRONG`` bit, the old target object is
  * unreferenced, and a reference is added to the new target object.
  *
  * Returns: %true on success, %false on failure.
@@ -1603,16 +1603,16 @@ void object_property_allow_set_link(const Object *obj, const char *name,
  *
  * Links form the graph in the object model.
  *
- * The <code>@check()</code> callback is invoked when
+ * The @check() callback is invoked when
  * object_property_set_link() is called and can raise an error to prevent the
- * link being set.  If <code>@check</code> is NULL, the property is read-only
+ * link being set.  If @check is NULL, the property is read-only
  * and cannot be set.

include/qom/object.h void object_property_allow_set_link(const Object *obj, const char *name, · line 1617

Quoted 10 lines
include/qom/object.h +2 -2
  *
  * Ownership of the pointer that @child points to is transferred to the
- * link property.  The reference count for <code>*@child</code> is
+ * link property.  The reference count for *@child is
  * managed by the property from after the function returns till the
  * property is deleted with object_property_del().  If the
- * <code>@flags</code> <code>OBJ_PROP_LINK_STRONG</code> bit is set,
+ * @flags ``OBJ_PROP_LINK_STRONG`` bit is set,
  * the reference count is decremented when the property is deleted or
  * modified.

You can use % too in this case and in the first hunk above; there's actually no difference between ``a`` and %a except the latter is shorter. Linux generally prefers %a, though kernel-doc also knows about ``a`` so that ``%x`` is interpreted correctly when the percent sign should be a literal.

Apart from that.

Paolo

Quoted 11 lines
include/qom/object.h +1 -1
  *
@@ -1823,7 +1823,7 @@ ObjectProperty *object_class_property_add_uint64_ptr(ObjectClass *klass,
  * Add an alias for a property on an object.  This function will add a property
  * of the same type as the forwarded property.
  *
- * The caller must ensure that <code>@target_obj</code> stays alive as long as
+ * The caller must ensure that @target_obj stays alive as long as
  * this property exists.  In the case of a child object or an alias on the same
  * object this will be the case.  For aliases to other objects the caller is
  * responsible for taking a reference.
#9 lore raw

PATCH 6/6 docs/devel/qom: Avoid long lines

In reply to Eduardo Habkost

Long code lines don't look good in the rendered documents, make them shorter.

---
 docs/devel/qom.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
docs/devel/qom.rst +6 -3
index 0c610e20d62..42d0dc4f4da 100644
@@ -284,7 +284,8 @@ in the header file:
 .. code-block:: c
    :caption: Declaring a simple type
 
-   OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device,
+                              MY_DEVICE, DEVICE)
 
 This is equivalent to the following:
 
@@ -360,7 +361,8 @@ This accepts an array of interface type names.
 
    OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
                                       MY_DEVICE, DEVICE,
-                                      { TYPE_USER_CREATABLE }, { NULL })
+                                      { TYPE_USER_CREATABLE },
+                                      { NULL })
 
 If the type is not intended to be instantiated, then then
 the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
@@ -368,7 +370,8 @@ the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
 .. code-block:: c
    :caption: Defining a simple abstract type
 
-   OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device,
+                               MY_DEVICE, DEVICE)
 
 
 
Signature · 1 line
2.26.2
Reviewed-by on v1 6/6
#10 lore raw

Re: [PATCH 6/6] docs/devel/qom: Avoid long lines

Quoted 4 lines · Eduardo Habkost

Long code lines don't look good in the rendered documents, make them shorter.

Quoted 39 lines
---
 docs/devel/qom.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
docs/devel/qom.rst +6 -3
index 0c610e20d62..42d0dc4f4da 100644
@@ -284,7 +284,8 @@ in the header file:
 .. code-block:: c
    :caption: Declaring a simple type
 
-   OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DECLARE_SIMPLE_TYPE(MyDevice, my_device,
+                              MY_DEVICE, DEVICE)
 
 This is equivalent to the following:
 
@@ -360,7 +361,8 @@ This accepts an array of interface type names.
 
    OBJECT_DEFINE_TYPE_WITH_INTERFACES(MyDevice, my_device,
                                       MY_DEVICE, DEVICE,
-                                      { TYPE_USER_CREATABLE }, { NULL })
+                                      { TYPE_USER_CREATABLE },
+                                      { NULL })
 
 If the type is not intended to be instantiated, then then
 the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
@@ -368,7 +370,8 @@ the OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead:
 .. code-block:: c
    :caption: Defining a simple abstract type
 
-   OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device, MY_DEVICE, DEVICE)
+   OBJECT_DEFINE_ABSTRACT_TYPE(MyDevice, my_device,
+                               MY_DEVICE, DEVICE)
 
 
 
Reviewed-by on the v1 series
#11 lore raw
In reply to Eduardo Habkost
Quoted 11 lines · Eduardo Habkost

A few fixes to the QOM documentation in docs/devel/qom.rst and include/qom/object.h.

Eduardo Habkost (6):
qom: Fix DECLARE_*CHECKER documentation docs/devel/qom: Fix indentation of bulleted list docs/devel/qom: Fix indentation of code blocks docs/devel/qom: Use *emphasis* for emphasis docs/devel/qom: Remove usage of <code> docs/devel/qom: Avoid long lines

Quoted 4 lines
 docs/devel/qom.rst   | 91 +++++++++++++++++++++++---------------------
 include/qom/object.h | 16 ++++----
 2 files changed, 55 insertions(+), 52 deletions(-)

though see patch 5 for a small note that can even be fixed without a v2.

Paolo