| Message ID | 20230619171437.357374-5-alex.bennee@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs/devel: improve API documentation for QOM | expand |
On 19/6/23 19:14, Alex Bennée wrote: > Lets try and keep the overview of the sub-system digestible by > splitting the core API stuff into a separate file. As QOM and QDEV > work together we should also try and enumerate the qdev_ functions. > Currently this is a little broken as kerneldoc doesn't understand our > macros. > > Signed-off-by: Alex Bennée <alex.bennee@linaro.org> > --- > docs/devel/index-api.rst | 2 ++ > docs/devel/qdev-api.rst | 12 ++++++++++++ > docs/devel/qom-api.rst | 9 +++++++++ > docs/devel/qom.rst | 3 ++- > 4 files changed, 25 insertions(+), 1 deletion(-) > create mode 100644 docs/devel/qdev-api.rst > create mode 100644 docs/devel/qom-api.rst Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
On 6/19/23 19:14, Alex Bennée wrote: > +We don't currently generate the API documentation for QDEV due to QEMU > +macros confusing the kerneldoc tool. For now see the headers in > +``include/hw/qdev-core.h`` > + > +.. > + kernel-doc:: include/hw/qdev-core.h I'm confused. Isn't that exactly what you're doing here? r~
On 20/6/23 12:03, Richard Henderson wrote: > On 6/19/23 19:14, Alex Bennée wrote: >> +We don't currently generate the API documentation for QDEV due to QEMU >> +macros confusing the kerneldoc tool. For now see the headers in >> +``include/hw/qdev-core.h`` >> + >> +.. >> + kernel-doc:: include/hw/qdev-core.h > > I'm confused. Isn't that exactly what you're doing here? IIUC the kernel-doc style comments from "hw/qdev-core.h" are embedded as rST doc, see: https://kernel.readthedocs.io/en/sphinx-samples/kernel-documentation.html#including-kernel-doc-comments
diff --git a/docs/devel/index-api.rst b/docs/devel/index-api.rst index 7108821746..539ad29c21 100644 --- a/docs/devel/index-api.rst +++ b/docs/devel/index-api.rst @@ -11,5 +11,7 @@ generated from in-code annotations to function prototypes. loads-stores memory modules + qom-api + qdev-api ui zoned-storage diff --git a/docs/devel/qdev-api.rst b/docs/devel/qdev-api.rst new file mode 100644 index 0000000000..d47c4d7493 --- /dev/null +++ b/docs/devel/qdev-api.rst @@ -0,0 +1,12 @@ +.. _qdev-api: + +================================ +QEMU Device (qdev) API Reference +================================ + +We don't currently generate the API documentation for QDEV due to QEMU +macros confusing the kerneldoc tool. For now see the headers in +``include/hw/qdev-core.h`` + +.. + kernel-doc:: include/hw/qdev-core.h diff --git a/docs/devel/qom-api.rst b/docs/devel/qom-api.rst new file mode 100644 index 0000000000..ed1f17e797 --- /dev/null +++ b/docs/devel/qom-api.rst @@ -0,0 +1,9 @@ +.. _qom-api: + +===================================== +QEMU Object Model (QOM) API Reference +===================================== + +This is the complete API documentation for :ref:`qom`. + +.. kernel-doc:: include/qom/object.h diff --git a/docs/devel/qom.rst b/docs/devel/qom.rst index c9237950d0..98a4f178d5 100644 --- a/docs/devel/qom.rst +++ b/docs/devel/qom.rst @@ -387,4 +387,5 @@ OBJECT_DEFINE_ABSTRACT_TYPE() macro can be used instead: API Reference ------------- -.. kernel-doc:: include/qom/object.h +See the :ref:`QOM API<qom-api>` and :ref:`QDEV API<qdev-api>` +documents for the complete API description.
Lets try and keep the overview of the sub-system digestible by splitting the core API stuff into a separate file. As QOM and QDEV work together we should also try and enumerate the qdev_ functions. Currently this is a little broken as kerneldoc doesn't understand our macros. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> --- docs/devel/index-api.rst | 2 ++ docs/devel/qdev-api.rst | 12 ++++++++++++ docs/devel/qom-api.rst | 9 +++++++++ docs/devel/qom.rst | 3 ++- 4 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 docs/devel/qdev-api.rst create mode 100644 docs/devel/qom-api.rst