qom documentation fixes
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
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
@@ -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
Re: [PATCH 1/6] qom: Fix DECLARE_*CHECKER documentation
Quoted 13 lines · Eduardo Habkost
Correct copy/paste mistake in the
DECLARE_INSTANCE_CHECKERandDECLARE_CLASS_CHECKERSdocumentation.Signed-off-by Eduardo Habkost <[email protected]>--- include/qom/object.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)include/qom/object.h +0
-0
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 ) \
PATCH 2/6 docs/devel/qom: Fix indentation of bulleted list
In reply to Eduardo HabkostThe 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
@@ -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
PATCH 3/6 docs/devel/qom: Fix indentation of code blocks
In reply to Eduardo HabkostSome 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
@@ -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
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
@@ -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
Re: [PATCH 4/6] docs/devel/qom: Use *emphasis* for emphasis
Quoted 3 lines · Eduardo Habkost
<emphasis> is not valid reST syntax.
Signed-off-by Eduardo Habkost <[email protected]>
Quoted 30 lines
--- docs/devel/qom.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)docs/devel/qom.rst +3
-3@@ -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
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
@@ -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
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
Signed-off-by Eduardo Habkost <[email protected]>--- include/qom/object.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)include/qom/object.h +3
-3@@ -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.
PATCH 6/6 docs/devel/qom: Avoid long lines
In reply to Eduardo HabkostLong 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
@@ -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
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.
Signed-off-by Eduardo Habkost <[email protected]>
Quoted 39 lines
--- docs/devel/qom.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)docs/devel/qom.rst +6
-3@@ -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)
Quoted 11 lines · Eduardo Habkost
A few fixes to the QOM documentation in
docs/devel/qom.rstandinclude/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