| Message ID | 20210729175554.686474-2-ehabkost@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | QOM documentation updates | expand |
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
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).
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
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.
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
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.
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)
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 ===============================================
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(-)