| Message ID | 20240205074709.3613229-4-armbru@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: Require member documentation (with loophole) | expand |
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
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| *
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(-)