The doc comment for qtest_cb_for_every_machine has a stray
space at the start of its description, which makes kernel-doc
think that this line is part of the documentation of the
skip_old_versioned argument. The result is that the HTML
doesn't have a "Description" section and the text is instead
put in the wrong place.

Remove the stray space.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 tests/qtest/libqtest.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/qtest/libqtest.h b/tests/qtest/libqtest.h
index b3f2e7fbefd..fd27521a9c7 100644
--- a/tests/qtest/libqtest.h
+++ b/tests/qtest/libqtest.h
@@ -977,7 +977,7 @@ void qtest_qmp_fds_assert_success(QTestState *qts, int *fds, size_t nfds,
  * @cb: Pointer to the callback function
  * @skip_old_versioned: true if versioned old machine types should be skipped
  *
- *  Call a callback function for every name of all available machines.
+ * Call a callback function for every name of all available machines.
  */
 void qtest_cb_for_every_machine(void (*cb)(const char *machine),
                                 bool skip_old_versioned);
-- 
2.43.0

Em Thu, 14 Aug 2025 18:13:17 +0100
Peter Maydell <peter.maydell@linaro.org> escreveu:

> The doc comment for qtest_cb_for_every_machine has a stray
> space at the start of its description, which makes kernel-doc
> think that this line is part of the documentation of the
> skip_old_versioned argument. The result is that the HTML
> doesn't have a "Description" section and the text is instead
> put in the wrong place.
> 
> Remove the stray space.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

LGTM. Even the previous version should have handled it wrong here
(if not, it is a bug there - or perhaps QEMU version was using
a very old kernel-doc.pl  version).

Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>


> ---
>  tests/qtest/libqtest.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/tests/qtest/libqtest.h b/tests/qtest/libqtest.h
> index b3f2e7fbefd..fd27521a9c7 100644
> --- a/tests/qtest/libqtest.h
> +++ b/tests/qtest/libqtest.h
> @@ -977,7 +977,7 @@ void qtest_qmp_fds_assert_success(QTestState *qts, int *fds, size_t nfds,
>   * @cb: Pointer to the callback function
>   * @skip_old_versioned: true if versioned old machine types should be skipped
>   *
> - *  Call a callback function for every name of all available machines.
> + * Call a callback function for every name of all available machines.
>   */
>  void qtest_cb_for_every_machine(void (*cb)(const char *machine),
>                                  bool skip_old_versioned);



Thanks,
Mauro

On Fri, 15 Aug 2025 at 10:51, Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> Em Thu, 14 Aug 2025 18:13:17 +0100
> Peter Maydell <peter.maydell@linaro.org> escreveu:
>
> > The doc comment for qtest_cb_for_every_machine has a stray
> > space at the start of its description, which makes kernel-doc
> > think that this line is part of the documentation of the
> > skip_old_versioned argument. The result is that the HTML
> > doesn't have a "Description" section and the text is instead
> > put in the wrong place.
> >
> > Remove the stray space.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>
> LGTM. Even the previous version should have handled it wrong here
> (if not, it is a bug there - or perhaps QEMU version was using
> a very old kernel-doc.pl  version).

Yes, the documentation comes out looking wrong on the
old version too -- I only noticed this because I was
examining the diffs of the HTML for before and after
and the exact way it's rendered changed, so it showed up.
Easiest way to reduce the diff was to fix our markup
error :-)

You can see how the old version outputs it at:

https://www.qemu.org/docs/master/devel/testing/qtest.html#c.qtest_cb_for_every_machine

-- PMM