[PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation

[PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation

[Eduardo Habkost]

This moves the QTest section of testing.rst to a separate
document, and include the QTest Protocol specification and
libqtest API reference in the document.

Eduardo Habkost (3):
  docs: Move QTest documentation to its own document
  docs/devel/qtest: Include protocol spec in document
  docs/devel/qtest: Include libqtest API reference

 docs/devel/index.rst          |  1 +
 docs/devel/qtest.rst          | 72 ++++++++++++++++++++++++++++++++++
 docs/devel/testing.rst        | 47 +---------------------
 tests/qtest/libqos/libqtest.h | 20 +++++-----
 softmmu/qtest.c               | 73 +++++++++++++++++++++++++++++++----
 5 files changed, 150 insertions(+), 63 deletions(-)
 create mode 100644 docs/devel/qtest.rst

-- 
2.26.2

[PATCH 1/3] docs: Move QTest documentation to its own document

[Eduardo Habkost]

The qtest and libqtest doc comments will be parsed to generate
API documentation, so move QTest documentation to its own
document where the API and format documentation and will be
included.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/index.rst   |  1 +
 docs/devel/qtest.rst   | 58 ++++++++++++++++++++++++++++++++++++++++++
 docs/devel/testing.rst | 47 ++--------------------------------
 3 files changed, 61 insertions(+), 45 deletions(-)
 create mode 100644 docs/devel/qtest.rst

diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index c34b43ec28e..d147b900a98 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -21,6 +21,7 @@ Contents:
    atomics
    stable-process
    testing
+   qtest
    decodetree
    secure-coding-practices
    tcg
diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
new file mode 100644
index 00000000000..86dec84a0ba
--- /dev/null
+++ b/docs/devel/qtest.rst
@@ -0,0 +1,58 @@
+========================================
+QTest Device Emulation Testing Framework
+========================================
+
+QTest is a device emulation testing framework.  It can be very useful to test
+device models; it could also control certain aspects of QEMU (such as virtual
+clock stepping), with a special purpose "qtest" protocol.  Refer to the
+documentation in ``qtest.c`` for more details of the protocol.
+
+QTest cases can be executed with
+
+.. code::
+
+   make check-qtest
+
+The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is
+defined in ``tests/qtest/libqtest.h``.
+
+Consider adding a new QTest case when you are introducing a new virtual
+hardware, or extending one if you are adding functionalities to an existing
+virtual device.
+
+On top of libqtest, a higher level library, ``libqos``, was created to
+encapsulate common tasks of device drivers, such as memory management and
+communicating with system buses or devices. Many virtual device tests use
+libqos instead of directly calling into libqtest.
+
+Steps to add a new QTest case are:
+
+1. Create a new source file for the test. (More than one file can be added as
+   necessary.) For example, ``tests/qtest/foo-test.c``.
+
+2. Write the test code with the glib and libqtest/libqos API. See also existing
+   tests and the library headers for reference.
+
+3. Register the new test in ``tests/qtest/Makefile.include``. Add the test
+   executable name to an appropriate ``check-qtest-*-y`` variable. For example:
+
+   ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)``
+
+4. Add object dependencies of the executable in the Makefile, including the
+   test source file(s) and other interesting objects. For example:
+
+   ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)``
+
+Debugging a QTest failure is slightly harder than the unit test because the
+tests look up QEMU program names in the environment variables, such as
+``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
+to attach gdb to the QEMU process spawned from the test. But manual invoking
+and using gdb on the test is still simple to do: find out the actual command
+from the output of
+
+.. code::
+
+  make check-qtest V=1
+
+which you can run manually.
+
diff --git a/docs/devel/testing.rst b/docs/devel/testing.rst
index bd64c1bdcdd..a171494b4e5 100644
--- a/docs/devel/testing.rst
+++ b/docs/devel/testing.rst
@@ -70,8 +70,8 @@ QTest
 
 QTest is a device emulation testing framework.  It can be very useful to test
 device models; it could also control certain aspects of QEMU (such as virtual
-clock stepping), with a special purpose "qtest" protocol.  Refer to the
-documentation in ``qtest.c`` for more details of the protocol.
+clock stepping), with a special purpose "qtest" protocol.  Refer to
+:doc:`qtest` for more details.
 
 QTest cases can be executed with
 
@@ -79,49 +79,6 @@ QTest cases can be executed with
 
    make check-qtest
 
-The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is
-defined in ``tests/qtest/libqtest.h``.
-
-Consider adding a new QTest case when you are introducing a new virtual
-hardware, or extending one if you are adding functionalities to an existing
-virtual device.
-
-On top of libqtest, a higher level library, ``libqos``, was created to
-encapsulate common tasks of device drivers, such as memory management and
-communicating with system buses or devices. Many virtual device tests use
-libqos instead of directly calling into libqtest.
-
-Steps to add a new QTest case are:
-
-1. Create a new source file for the test. (More than one file can be added as
-   necessary.) For example, ``tests/qtest/foo-test.c``.
-
-2. Write the test code with the glib and libqtest/libqos API. See also existing
-   tests and the library headers for reference.
-
-3. Register the new test in ``tests/qtest/Makefile.include``. Add the test
-   executable name to an appropriate ``check-qtest-*-y`` variable. For example:
-
-   ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)``
-
-4. Add object dependencies of the executable in the Makefile, including the
-   test source file(s) and other interesting objects. For example:
-
-   ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)``
-
-Debugging a QTest failure is slightly harder than the unit test because the
-tests look up QEMU program names in the environment variables, such as
-``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
-to attach gdb to the QEMU process spawned from the test. But manual invoking
-and using gdb on the test is still simple to do: find out the actual command
-from the output of
-
-.. code::
-
-  make check-qtest V=1
-
-which you can run manually.
-
 QAPI schema tests
 -----------------
 
-- 
2.26.2

[PATCH 2/3] docs/devel/qtest: Include protocol spec in document

[Eduardo Habkost]

Include the QTest Protocol doc string in docs/devel/qtest.rst,
after converting it to use Sphinx syntax.

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qtest.rst | 12 ++++++--
 softmmu/qtest.c      | 73 +++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 75 insertions(+), 10 deletions(-)

diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
index 86dec84a0ba..3bf9ebee7f0 100644
--- a/docs/devel/qtest.rst
+++ b/docs/devel/qtest.rst
@@ -4,8 +4,8 @@ QTest Device Emulation Testing Framework
 
 QTest is a device emulation testing framework.  It can be very useful to test
 device models; it could also control certain aspects of QEMU (such as virtual
-clock stepping), with a special purpose "qtest" protocol.  Refer to the
-documentation in ``qtest.c`` for more details of the protocol.
+clock stepping), with a special purpose "qtest" protocol.  Refer to
+:ref:`qtest-protocol` for more details of the protocol.
 
 QTest cases can be executed with
 
@@ -56,3 +56,11 @@ from the output of
 
 which you can run manually.
 
+
+.. _qtest-protocol:
+
+QTest Protocol
+--------------
+
+.. kernel-doc:: softmmu/qtest.c
+   :doc: QTest Protocol
diff --git a/softmmu/qtest.c b/softmmu/qtest.c
index 4e439caec7e..9382fd25439 100644
--- a/softmmu/qtest.c
+++ b/softmmu/qtest.c
@@ -49,92 +49,141 @@ static void *qtest_server_send_opaque;
 #define FMT_timeval "%ld.%06ld"
 
 /**
- * QTest Protocol
+ * DOC: QTest Protocol
+ *
+ * .. highlight:: none
  *
  * Line based protocol, request/response based.  Server can send async messages
  * so clients should always handle many async messages before the response
  * comes in.
  *
  * Valid requests
+ * ^^^^^^^^^^^^^^
  *
  * Clock management:
+ * """""""""""""""""
  *
  * The qtest client is completely in charge of the QEMU_CLOCK_VIRTUAL.  qtest commands
  * let you adjust the value of the clock (monotonically).  All the commands
  * return the current value of the clock in nanoseconds.
  *
+ * .. code-block::
+ *
  *  > clock_step
  *  < OK VALUE
  *
- *     Advance the clock to the next deadline.  Useful when waiting for
- *     asynchronous events.
+ * Advance the clock to the next deadline.  Useful when waiting for
+ * asynchronous events.
+ *
+ * .. code-block::
  *
  *  > clock_step NS
  *  < OK VALUE
  *
- *     Advance the clock by NS nanoseconds.
+ * Advance the clock by NS nanoseconds.
+ *
+ * .. code-block::
  *
  *  > clock_set NS
  *  < OK VALUE
  *
- *     Advance the clock to NS nanoseconds (do nothing if it's already past).
+ * Advance the clock to NS nanoseconds (do nothing if it's already past).
  *
  * PIO and memory access:
+ * """"""""""""""""""""""
+ *
+ * .. code-block::
  *
  *  > outb ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > outw ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > outl ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > inb ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > inw ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > inl ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > writeb ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > writew ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > writel ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > writeq ADDR VALUE
  *  < OK
  *
+ * .. code-block::
+ *
  *  > readb ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > readw ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > readl ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > readq ADDR
  *  < OK VALUE
  *
+ * .. code-block::
+ *
  *  > read ADDR SIZE
  *  < OK DATA
  *
+ * .. code-block::
+ *
  *  > write ADDR SIZE DATA
  *  < OK
  *
+ * .. code-block::
+ *
  *  > b64read ADDR SIZE
  *  < OK B64_DATA
  *
+ * .. code-block::
+ *
  *  > b64write ADDR SIZE B64_DATA
  *  < OK
  *
+ * .. code-block::
+ *
  *  > memset ADDR SIZE VALUE
  *  < OK
  *
@@ -149,16 +198,21 @@ static void *qtest_server_send_opaque;
  * If the sizes do not match, the data will be truncated.
  *
  * IRQ management:
+ * """""""""""""""
+ *
+ * .. code-block::
  *
  *  > irq_intercept_in QOM-PATH
  *  < OK
  *
+ * .. code-block::
+ *
  *  > irq_intercept_out QOM-PATH
  *  < OK
  *
  * Attach to the gpio-in (resp. gpio-out) pins exported by the device at
  * QOM-PATH.  When the pin is triggered, one of the following async messages
- * will be printed to the qtest stream:
+ * will be printed to the qtest stream::
  *
  *  IRQ raise NUM
  *  IRQ lower NUM
@@ -168,12 +222,15 @@ static void *qtest_server_send_opaque;
  * NUM=0 even though it is remapped to GSI 2).
  *
  * Setting interrupt level:
+ * """"""""""""""""""""""""
+ *
+ * .. code-block::
  *
  *  > set_irq_in QOM-PATH NAME NUM LEVEL
  *  < OK
  *
- *  where NAME is the name of the irq/gpio list, NUM is an IRQ number and
- *  LEVEL is an signed integer IRQ level.
+ * where NAME is the name of the irq/gpio list, NUM is an IRQ number and
+ * LEVEL is an signed integer IRQ level.
  *
  * Forcibly set the given interrupt pin to the given level.
  *
-- 
2.26.2

Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document

[Paolo Bonzini]

On 05/10/20 22:52, Eduardo Habkost wrote:
> + * DOC: QTest Protocol
> + *
> + * .. highlight:: none
>   *
>   * Line based protocol, request/response based.  Server can send async messages
>   * so clients should always handle many async messages before the response
>   * comes in.
>   *
>   * Valid requests
> + * ^^^^^^^^^^^^^^
>   *
>   * Clock management:
> + * """""""""""""""""
>   *
>   * The qtest client is completely in charge of the QEMU_CLOCK_VIRTUAL.  qtest commands
>   * let you adjust the value of the clock (monotonically).  All the commands
>   * return the current value of the clock in nanoseconds.
>   *
> + * .. code-block::

What version of Sphinx do you have?  I need to have ".. code-block::
none" here, so presumably the "highlight" directive is newer than my
version (1.7.6, pretty old I admit)?

Paolo

Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document

[Eduardo Habkost]

On Wed, Oct 07, 2020 at 01:03:21PM +0200, Paolo Bonzini wrote:
> On 05/10/20 22:52, Eduardo Habkost wrote:
> > + * DOC: QTest Protocol
> > + *
> > + * .. highlight:: none
> >   *
> >   * Line based protocol, request/response based.  Server can send async messages
> >   * so clients should always handle many async messages before the response
> >   * comes in.
> >   *
> >   * Valid requests
> > + * ^^^^^^^^^^^^^^
> >   *
> >   * Clock management:
> > + * """""""""""""""""
> >   *
> >   * The qtest client is completely in charge of the QEMU_CLOCK_VIRTUAL.  qtest commands
> >   * let you adjust the value of the clock (monotonically).  All the commands
> >   * return the current value of the clock in nanoseconds.
> >   *
> > + * .. code-block::
> 
> What version of Sphinx do you have?  I need to have ".. code-block::
> none" here, so presumably the "highlight" directive is newer than my
> version (1.7.6, pretty old I admit)?

I have 2.2.2.

It looks like we should really add code to print a warning if not
running Sphinx 2.x.

-- 
Eduardo

Re: [PATCH 2/3] docs/devel/qtest: Include protocol spec in document

[Paolo Bonzini]

On 07/10/20 13:39, Eduardo Habkost wrote:
>> What version of Sphinx do you have?  I need to have ".. code-block::
>> none" here, so presumably the "highlight" directive is newer than my
>> version (1.7.6, pretty old I admit)?
> I have 2.2.2.
> 
> It looks like we should really add code to print a warning if not
> running Sphinx 2.x.

1.x seems to work just fine though, and it's what is included in RHEL8
"CodeReady Linux Builder" repository
(https://developers.redhat.com/blog/2018/11/15/introducing-codeready-linux-builder/).

Paolo

[PATCH 3/3] docs/devel/qtest: Include libqtest API reference

[Eduardo Habkost]

Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
---
 docs/devel/qtest.rst          |  6 ++++++
 tests/qtest/libqos/libqtest.h | 20 ++++++++++----------
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
index 3bf9ebee7f0..075fe5f7d53 100644
--- a/docs/devel/qtest.rst
+++ b/docs/devel/qtest.rst
@@ -64,3 +64,9 @@ QTest Protocol
 
 .. kernel-doc:: softmmu/qtest.c
    :doc: QTest Protocol
+
+
+libqtest API reference
+----------------------
+
+.. kernel-doc:: tests/qtest/libqos/libqtest.h
diff --git a/tests/qtest/libqos/libqtest.h b/tests/qtest/libqos/libqtest.h
index a6ee1654f20..209fcf69737 100644
--- a/tests/qtest/libqos/libqtest.h
+++ b/tests/qtest/libqos/libqtest.h
@@ -24,7 +24,7 @@ typedef struct QTestState QTestState;
 
 /**
  * qtest_initf:
- * @fmt...: Format for creating other arguments to pass to QEMU, formatted
+ * @fmt: Format for creating other arguments to pass to QEMU, formatted
  * like sprintf().
  *
  * Convenience wrapper around qtest_init().
@@ -87,7 +87,7 @@ void qtest_quit(QTestState *s);
  * @s: #QTestState instance to operate on.
  * @fds: array of file descriptors
  * @fds_num: number of elements in @fds
- * @fmt...: QMP message to send to qemu, formatted like
+ * @fmt: QMP message to send to qemu, formatted like
  * qobject_from_jsonf_nofail().  See parse_escape() for what's
  * supported after '%'.
  *
@@ -100,7 +100,7 @@ QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num,
 /**
  * qtest_qmp:
  * @s: #QTestState instance to operate on.
- * @fmt...: QMP message to send to qemu, formatted like
+ * @fmt: QMP message to send to qemu, formatted like
  * qobject_from_jsonf_nofail().  See parse_escape() for what's
  * supported after '%'.
  *
@@ -112,7 +112,7 @@ QDict *qtest_qmp(QTestState *s, const char *fmt, ...)
 /**
  * qtest_qmp_send:
  * @s: #QTestState instance to operate on.
- * @fmt...: QMP message to send to qemu, formatted like
+ * @fmt: QMP message to send to qemu, formatted like
  * qobject_from_jsonf_nofail().  See parse_escape() for what's
  * supported after '%'.
  *
@@ -124,7 +124,7 @@ void qtest_qmp_send(QTestState *s, const char *fmt, ...)
 /**
  * qtest_qmp_send_raw:
  * @s: #QTestState instance to operate on.
- * @fmt...: text to send, formatted like sprintf()
+ * @fmt: text to send, formatted like sprintf()
  *
  * Sends text to the QMP monitor verbatim.  Need not be valid JSON;
  * this is useful for negative tests.
@@ -201,7 +201,7 @@ QDict *qtest_qmp_receive(QTestState *s);
 /**
  * qtest_qmp_eventwait:
  * @s: #QTestState instance to operate on.
- * @s: #event event to wait for.
+ * @event: event to wait for.
  *
  * Continuously polls for QMP responses until it receives the desired event.
  */
@@ -210,7 +210,7 @@ void qtest_qmp_eventwait(QTestState *s, const char *event);
 /**
  * qtest_qmp_eventwait_ref:
  * @s: #QTestState instance to operate on.
- * @s: #event event to wait for.
+ * @event: event to wait for.
  *
  * Continuously polls for QMP responses until it receives the desired event.
  * Returns a copy of the event for further investigation.
@@ -237,7 +237,7 @@ QDict *qtest_qmp_receive_success(QTestState *s,
 /**
  * qtest_hmp:
  * @s: #QTestState instance to operate on.
- * @fmt...: HMP command to send to QEMU, formats arguments like sprintf().
+ * @fmt: HMP command to send to QEMU, formats arguments like sprintf().
  *
  * Send HMP command to QEMU via QMP's human-monitor-command.
  * QMP events are discarded.
@@ -629,7 +629,7 @@ void qtest_add_abrt_handler(GHookFunc fn, const void *data);
 /**
  * qtest_qmp_assert_success:
  * @qts: QTestState instance to operate on
- * @fmt...: QMP message to send to qemu, formatted like
+ * @fmt: QMP message to send to qemu, formatted like
  * qobject_from_jsonf_nofail().  See parse_escape() for what's
  * supported after '%'.
  *
@@ -676,7 +676,7 @@ void qtest_qmp_device_add_qdict(QTestState *qts, const char *drv,
  * @qts: QTestState instance to operate on
  * @driver: Name of the device that should be added
  * @id: Identification string
- * @fmt...: QMP message to send to qemu, formatted like
+ * @fmt: QMP message to send to qemu, formatted like
  * qobject_from_jsonf_nofail().  See parse_escape() for what's
  * supported after '%'.
  *
-- 
2.26.2

Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference

[Thomas Huth]

On 05/10/2020 22.52, Eduardo Habkost wrote:
> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> ---
>   docs/devel/qtest.rst          |  6 ++++++
>   tests/qtest/libqos/libqtest.h | 20 ++++++++++----------
>   2 files changed, 16 insertions(+), 10 deletions(-)
> 
> diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
> index 3bf9ebee7f0..075fe5f7d53 100644
> --- a/docs/devel/qtest.rst
> +++ b/docs/devel/qtest.rst
> @@ -64,3 +64,9 @@ QTest Protocol
>   
>   .. kernel-doc:: softmmu/qtest.c
>      :doc: QTest Protocol
> +
> +
> +libqtest API reference
> +----------------------
> +
> +.. kernel-doc:: tests/qtest/libqos/libqtest.h
> diff --git a/tests/qtest/libqos/libqtest.h b/tests/qtest/libqos/libqtest.h
> index a6ee1654f20..209fcf69737 100644
> --- a/tests/qtest/libqos/libqtest.h
> +++ b/tests/qtest/libqos/libqtest.h
> @@ -24,7 +24,7 @@ typedef struct QTestState QTestState;
>   
>   /**
>    * qtest_initf:
> - * @fmt...: Format for creating other arguments to pass to QEMU, formatted
> + * @fmt: Format for creating other arguments to pass to QEMU, formatted
>    * like sprintf().
>    *
>    * Convenience wrapper around qtest_init().
> @@ -87,7 +87,7 @@ void qtest_quit(QTestState *s);
>    * @s: #QTestState instance to operate on.
>    * @fds: array of file descriptors
>    * @fds_num: number of elements in @fds
> - * @fmt...: QMP message to send to qemu, formatted like
> + * @fmt: QMP message to send to qemu, formatted like
>    * qobject_from_jsonf_nofail().  See parse_escape() for what's
>    * supported after '%'.
>    *
> @@ -100,7 +100,7 @@ QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num,
>   /**
>    * qtest_qmp:
>    * @s: #QTestState instance to operate on.
> - * @fmt...: QMP message to send to qemu, formatted like
> + * @fmt: QMP message to send to qemu, formatted like

I think you should mention those changes to all those "fmt..." in the commit 
message?

  Thomas

Re: [PATCH 3/3] docs/devel/qtest: Include libqtest API reference

[Eduardo Habkost]

On Tue, Oct 06, 2020 at 07:12:17PM +0200, Thomas Huth wrote:
> On 05/10/2020 22.52, Eduardo Habkost wrote:
> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
> > ---
> >   docs/devel/qtest.rst          |  6 ++++++
> >   tests/qtest/libqos/libqtest.h | 20 ++++++++++----------
> >   2 files changed, 16 insertions(+), 10 deletions(-)
> > 
> > diff --git a/docs/devel/qtest.rst b/docs/devel/qtest.rst
> > index 3bf9ebee7f0..075fe5f7d53 100644
> > --- a/docs/devel/qtest.rst
> > +++ b/docs/devel/qtest.rst
> > @@ -64,3 +64,9 @@ QTest Protocol
> >   .. kernel-doc:: softmmu/qtest.c
> >      :doc: QTest Protocol
> > +
> > +
> > +libqtest API reference
> > +----------------------
> > +
> > +.. kernel-doc:: tests/qtest/libqos/libqtest.h
> > diff --git a/tests/qtest/libqos/libqtest.h b/tests/qtest/libqos/libqtest.h
> > index a6ee1654f20..209fcf69737 100644
> > --- a/tests/qtest/libqos/libqtest.h
> > +++ b/tests/qtest/libqos/libqtest.h
> > @@ -24,7 +24,7 @@ typedef struct QTestState QTestState;
> >   /**
> >    * qtest_initf:
> > - * @fmt...: Format for creating other arguments to pass to QEMU, formatted
> > + * @fmt: Format for creating other arguments to pass to QEMU, formatted
> >    * like sprintf().
> >    *
> >    * Convenience wrapper around qtest_init().
> > @@ -87,7 +87,7 @@ void qtest_quit(QTestState *s);
> >    * @s: #QTestState instance to operate on.
> >    * @fds: array of file descriptors
> >    * @fds_num: number of elements in @fds
> > - * @fmt...: QMP message to send to qemu, formatted like
> > + * @fmt: QMP message to send to qemu, formatted like
> >    * qobject_from_jsonf_nofail().  See parse_escape() for what's
> >    * supported after '%'.
> >    *
> > @@ -100,7 +100,7 @@ QDict *qtest_qmp_fds(QTestState *s, int *fds, size_t fds_num,
> >   /**
> >    * qtest_qmp:
> >    * @s: #QTestState instance to operate on.
> > - * @fmt...: QMP message to send to qemu, formatted like
> > + * @fmt: QMP message to send to qemu, formatted like
> 
> I think you should mention those changes to all those "fmt..." in the commit
> message?

Yes.  I mentioned "after converting it to Sphinx syntax" on patch
2/3, but forgot to mention the same thing in this patch.

-- 
Eduardo

Re: [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation

[Paolo Bonzini]

On 05/10/20 22:52, Eduardo Habkost wrote:
> This moves the QTest section of testing.rst to a separate
> document, and include the QTest Protocol specification and
> libqtest API reference in the document.
> 
> Eduardo Habkost (3):
>   docs: Move QTest documentation to its own document
>   docs/devel/qtest: Include protocol spec in document
>   docs/devel/qtest: Include libqtest API reference
> 
>  docs/devel/index.rst          |  1 +
>  docs/devel/qtest.rst          | 72 ++++++++++++++++++++++++++++++++++
>  docs/devel/testing.rst        | 47 +---------------------
>  tests/qtest/libqos/libqtest.h | 20 +++++-----
>  softmmu/qtest.c               | 73 +++++++++++++++++++++++++++++++----
>  5 files changed, 150 insertions(+), 63 deletions(-)
>  create mode 100644 docs/devel/qtest.rst
> 

The series is moving obsolete (non-mesonified) information.  I should
fix the docs at the same time, so I've queued it and will send the fix
on top.

Paolo

Re: [PATCH 0/3] docs: Include QTest protocol and libqtest API on documentation

[Thomas Huth]

On 05/10/2020 22.52, Eduardo Habkost wrote:
> This moves the QTest section of testing.rst to a separate
> document, and include the QTest Protocol specification and
> libqtest API reference in the document.
> 
> Eduardo Habkost (3):
>    docs: Move QTest documentation to its own document
>    docs/devel/qtest: Include protocol spec in document
>    docs/devel/qtest: Include libqtest API reference
> 
>   docs/devel/index.rst          |  1 +
>   docs/devel/qtest.rst          | 72 ++++++++++++++++++++++++++++++++++
>   docs/devel/testing.rst        | 47 +---------------------
>   tests/qtest/libqos/libqtest.h | 20 +++++-----
>   softmmu/qtest.c               | 73 +++++++++++++++++++++++++++++++----
>   5 files changed, 150 insertions(+), 63 deletions(-)
>   create mode 100644 docs/devel/qtest.rst

FWIW:

Acked-by: Thomas Huth <thuth@redhat.com>