[PATCH 03/15] qapi/block-core: Fix BlockLatencyHistogramInfo doc markup

Markus Armbruster posted 15 patches 9 months, 3 weeks ago
Maintainers: "Marc-André Lureau" <marcandre.lureau@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, Peter Maydell <peter.maydell@linaro.org>, "Michael S. Tsirkin" <mst@redhat.com>, Jason Wang <jasowang@redhat.com>, Eric Blake <eblake@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Gerd Hoffmann <kraxel@redhat.com>, Lukas Straub <lukasstraub2@web.de>, Konstantin Kostiuk <kkostiuk@redhat.com>
[PATCH 03/15] qapi/block-core: Fix BlockLatencyHistogramInfo doc markup
Posted by Markus Armbruster 9 months, 3 weeks ago
The description of @bins ends with a literal block:

    # @bins: list of io request counts corresponding to histogram
    #     intervals, one more element than @boundaries has.  For the
    #     example above, @bins may be something like [3, 1, 5, 2], and
    #     corresponding histogram looks like:
    #
    # ::
    #
    #        5|           *

Except it actually ends *before* the block: the unindented '::' line
starts a new section.  Makes no sense.

We could fix this by indenting the '::' line.  Instead, double the
colon at the end of the preceding paragraph, and drop the '::' line.

This shifts the box for the literal block right in generated
documentation, so it lines up with the description.

Fixes: commit a0fcff383b34 (qapi: Use rST markup for literal blocks)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/block-core.json | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 781c9bd03e..80ed4122f2 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -656,9 +656,7 @@
 # @bins: list of io request counts corresponding to histogram
 #     intervals, one more element than @boundaries has.  For the
 #     example above, @bins may be something like [3, 1, 5, 2], and
-#     corresponding histogram looks like:
-#
-# ::
+#     corresponding histogram looks like::
 #
 #        5|           *
 #        4|           *
-- 
2.43.0
Re: [PATCH 03/15] qapi/block-core: Fix BlockLatencyHistogramInfo doc markup
Posted by Daniel P. Berrangé 9 months, 3 weeks ago
On Mon, Feb 05, 2024 at 08:46:57AM +0100, Markus Armbruster wrote:
> The description of @bins ends with a literal block:
> 
>     # @bins: list of io request counts corresponding to histogram
>     #     intervals, one more element than @boundaries has.  For the
>     #     example above, @bins may be something like [3, 1, 5, 2], and
>     #     corresponding histogram looks like:
>     #
>     # ::
>     #
>     #        5|           *
> 
> Except it actually ends *before* the block: the unindented '::' line
> starts a new section.  Makes no sense.
> 
> We could fix this by indenting the '::' line.  Instead, double the
> colon at the end of the preceding paragraph, and drop the '::' line.
> 
> This shifts the box for the literal block right in generated
> documentation, so it lines up with the description.
> 
> Fixes: commit a0fcff383b34 (qapi: Use rST markup for literal blocks)
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/block-core.json | 4 +---
>  1 file changed, 1 insertion(+), 3 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|