Message ID | 20200309154405.13548-11-peter.maydell@linaro.org |
---|---|
State | Superseded |
Headers | show |
Series | Convert QAPI doc comments to generate rST instead of texinfo | expand |
On 3/9/20 8:43 AM, Peter Maydell wrote: > 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). > > 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 '::'. > > (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.) > > 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(-) Reviewed-by: Richard Henderson <richard.henderson@linaro.org> r~
diff --git a/qapi/block-core.json b/qapi/block-core.json index 85e27bb61f4..0c9c21927f9 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -550,13 +550,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 ff5aea59451..440fece703f 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -22,8 +22,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.
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). 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 '::'. (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.) 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(-) -- 2.20.1