From: Eduardo Habkost <ehabkost@redhat.com>
To: qemu-devel@nongnu.org
Cc: "Paolo Bonzini" <pbonzini@redhat.com>,
"Daniel P. Berrangé" <berrange@redhat.com>,
"Eduardo Habkost" <ehabkost@redhat.com>
Subject: [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol`
Date: Thu, 29 Jul 2021 13:55:45 -0400 [thread overview]
Message-ID: <20210729175554.686474-2-ehabkost@redhat.com> (raw)
In-Reply-To: <20210729175554.686474-1-ehabkost@redhat.com>
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
next prev parent reply other threads:[~2021-07-29 17:59 UTC|newest]
Thread overview: 32+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-07-29 17:55 [PATCH for-6.2 00/10] QOM documentation updates Eduardo Habkost
2021-07-29 17:55 ` Eduardo Habkost [this message]
2021-08-02 12:14 ` [PATCH for-6.2 01/10] docs: qom: Replace old GTK-Doc #symbol syntax with `symbol` Peter Maydell
2021-08-04 20:31 ` Eduardo Habkost
2021-08-04 20:42 ` Peter Maydell
2021-08-04 21:00 ` Eduardo Habkost
2021-08-05 0:26 ` John Snow
2021-08-05 16:36 ` Eduardo Habkost
2021-08-05 19:07 ` Eduardo Habkost
2021-07-29 17:55 ` [PATCH for-6.2 02/10] docs: qom: Use Sphinx cross references more often Eduardo Habkost
2021-07-29 17:55 ` [PATCH for-6.2 03/10] docs: qom: Fix autoptr expansion example Eduardo Habkost
2021-08-02 12:16 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 04/10] docs: qom: Fix "API Reference" heading level Eduardo Habkost
2021-08-02 12:16 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 05/10] docs: qom: Add subsection headings to declaration/definition macros section Eduardo Habkost
2021-07-30 13:15 ` Philippe Mathieu-Daudé
2021-08-02 12:17 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 06/10] docs: qom: Remove unnecessary class typedefs from example Eduardo Habkost
2021-07-30 8:16 ` Markus Armbruster
2021-07-30 8:43 ` Peter Maydell
2021-07-30 9:19 ` Daniel P. Berrangé
2021-08-02 12:19 ` Peter Maydell
2021-08-04 20:40 ` Eduardo Habkost
2021-08-04 20:45 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 07/10] docs: qom: Fix OBJECT_DECLARE_SIMPLE_TYPE documentation Eduardo Habkost
2021-08-02 12:24 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 08/10] docs: qom: Show actual typecast functions in examples Eduardo Habkost
2021-08-02 12:25 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 09/10] docs: qom: Remove OBJECT_CHECK macro examples Eduardo Habkost
2021-08-02 12:27 ` Peter Maydell
2021-07-29 17:55 ` [PATCH for-6.2 10/10] MAINTAINERS: Add qom.rst to QOM section Eduardo Habkost
2021-08-02 12:28 ` Peter Maydell
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20210729175554.686474-2-ehabkost@redhat.com \
--to=ehabkost@redhat.com \
--cc=berrange@redhat.com \
--cc=pbonzini@redhat.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).