| Message ID | 20200810195019.25427-13-peter.maydell@linaro.org |
|---|---|
| State | Accepted |
| Headers | show |
| Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
Peter Maydell <peter.maydell@linaro.org> writes: > There are exactly two places in our json doc comments where we > use the markup accepted by the texi doc generator where a '|' in > the first line of a doc comment means the line should be emitted > as a literal block (fixed-width font, whitespace preserved). Has always been pretty broken, though: each line ends up in its own @example environment. See doc-good.texi. > Since we use this syntax so rarely, instead of making the rST > generator support it, instead just convert the two uses to > rST-format literal blocks, which are indented and introduced > with '::'. Also, we should not reinvent what reST already provides. > (The rST generator doesn't complain about the old style syntax, > it just emits it with the '|' and with the whitespace not > preserved, which looks odd, but means we can safely leave this > change until after we've stopped generating texinfo.) In other words, the recent switch to the reST generator messed these examples up, and this commit tidies up. > Reviewed-by: Richard Henderson <richard.henderson@linaro.org> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > qapi/block-core.json | 16 +++++++++------- > qapi/qapi-schema.json | 6 ++++-- > 2 files changed, 13 insertions(+), 9 deletions(-) > > diff --git a/qapi/block-core.json b/qapi/block-core.json > index 535b2b2e7bf..12758116e85 100644 > --- a/qapi/block-core.json > +++ b/qapi/block-core.json > @@ -566,13 +566,15 @@ > # For the example above, @bins may be something like [3, 1, 5, 2], > # and corresponding histogram looks like: > # > -# | 5| * > -# | 4| * > -# | 3| * * > -# | 2| * * * > -# | 1| * * * * > -# | +------------------ > -# | 10 50 100 > +# :: > +# > +# 5| * > +# 4| * > +# 3| * * > +# 2| * * * > +# 1| * * * * > +# +------------------ > +# 10 50 100 > # > # Since: 4.0 > ## Could exploit that reST is the Perl of ASCII-based markups, and write # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like:: # # 5| * # 4| * # 3| * * # 2| * * * # 1| * * * * # +------------------ # 10 50 100 # # Since: 4.0 ## Matter of taste. I find both similarly arcane. > diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json > index 5fc0771eb04..c19b4267058 100644 > --- a/qapi/qapi-schema.json > +++ b/qapi/qapi-schema.json > @@ -23,8 +23,10 @@ > # > # Example: > # > -# | -> data issued by the Client > -# | <- Server data response > +# :: > +# > +# -> data issued by the Client > +# <- Server data response > # > # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for > # detailed information on the Server command and response formats. Likewise. Regardless:: Reviewed-by: Markus Armbruster <armbru@redhat.com>
diff --git a/qapi/block-core.json b/qapi/block-core.json index 535b2b2e7bf..12758116e85 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -566,13 +566,15 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# | 5| * -# | 4| * -# | 3| * * -# | 2| * * * -# | 1| * * * * -# | +------------------ -# | 10 50 100 +# :: +# +# 5| * +# 4| * +# 3| * * +# 2| * * * +# 1| * * * * +# +------------------ +# 10 50 100 # # Since: 4.0 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 5fc0771eb04..c19b4267058 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -23,8 +23,10 @@ # # Example: # -# | -> data issued by the Client -# | <- Server data response +# :: +# +# -> data issued by the Client +# <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats.