mirror of
https://github.com/Motorhead1991/qemu.git
synced 2025-08-02 15:23:53 -06:00
99dff36d3a
As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for Texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-5-peter.maydell@linaro.org> Signed-off-by: Markus Armbruster <armbru@redhat.com>
218 lines
3.5 KiB
Text
218 lines
3.5 KiB
Text
module None
|
|
object q_empty
|
|
enum QType
|
|
prefix QTYPE
|
|
member none
|
|
member qnull
|
|
member qnum
|
|
member qstring
|
|
member qdict
|
|
member qlist
|
|
member qbool
|
|
module doc-good.json
|
|
enum Enum
|
|
member one
|
|
if ['defined(IFONE)']
|
|
member two
|
|
if ['defined(IFCOND)']
|
|
feature enum-feat
|
|
object Base
|
|
member base1: Enum optional=False
|
|
object Variant1
|
|
member var1: str optional=False
|
|
if ['defined(IFSTR)']
|
|
feature member-feat
|
|
feature variant1-feat
|
|
object Variant2
|
|
object Object
|
|
base Base
|
|
tag base1
|
|
case one: Variant1
|
|
case two: Variant2
|
|
if ['IFTWO']
|
|
feature union-feat1
|
|
object q_obj_Variant1-wrapper
|
|
member data: Variant1 optional=False
|
|
object q_obj_Variant2-wrapper
|
|
member data: Variant2 optional=False
|
|
enum SugaredUnionKind
|
|
member one
|
|
member two
|
|
if ['IFTWO']
|
|
object SugaredUnion
|
|
member type: SugaredUnionKind optional=False
|
|
tag type
|
|
case one: q_obj_Variant1-wrapper
|
|
case two: q_obj_Variant2-wrapper
|
|
if ['IFTWO']
|
|
feature union-feat2
|
|
alternate Alternate
|
|
tag type
|
|
case i: int
|
|
case b: bool
|
|
feature alt-feat
|
|
object q_obj_cmd-arg
|
|
member arg1: int optional=False
|
|
member arg2: str optional=True
|
|
member arg3: bool optional=False
|
|
command cmd q_obj_cmd-arg -> Object
|
|
gen=True success_response=True boxed=False oob=False preconfig=False
|
|
feature cmd-feat1
|
|
feature cmd-feat2
|
|
command cmd-boxed Object -> None
|
|
gen=True success_response=True boxed=True oob=False preconfig=False
|
|
feature cmd-feat1
|
|
feature cmd-feat2
|
|
event EVT-BOXED Object
|
|
boxed=True
|
|
feature feat3
|
|
doc freeform
|
|
body=
|
|
= Section
|
|
doc freeform
|
|
body=
|
|
== Subsection
|
|
|
|
*strong* _with emphasis_
|
|
@var {in braces}
|
|
|
|
* List item one
|
|
* Two, multiple
|
|
lines
|
|
|
|
* Three
|
|
Still in list
|
|
|
|
Not in list
|
|
|
|
- Second list
|
|
Note: still in list
|
|
|
|
Note: not in list
|
|
|
|
1. Third list
|
|
is numbered
|
|
|
|
2. another item
|
|
|
|
Returns: the King
|
|
Since: the first age
|
|
Notes:
|
|
|
|
1. Lorem ipsum dolor sit amet
|
|
|
|
2. Ut enim ad minim veniam
|
|
|
|
Duis aute irure dolor
|
|
|
|
Example:
|
|
|
|
-> in
|
|
<- out
|
|
Examples:
|
|
- *verbatim*
|
|
- {braces}
|
|
doc symbol=Enum
|
|
body=
|
|
|
|
arg=one
|
|
The _one_ {and only}
|
|
arg=two
|
|
|
|
feature=enum-feat
|
|
Also _one_ {and only}
|
|
section=None
|
|
@two is undocumented
|
|
doc symbol=Base
|
|
body=
|
|
|
|
arg=base1
|
|
the first member
|
|
doc symbol=Variant1
|
|
body=
|
|
A paragraph
|
|
|
|
Another paragraph (but no @var: line)
|
|
arg=var1
|
|
|
|
feature=variant1-feat
|
|
a feature
|
|
feature=member-feat
|
|
a member feature
|
|
doc symbol=Variant2
|
|
body=
|
|
|
|
doc symbol=Object
|
|
body=
|
|
|
|
feature=union-feat1
|
|
a feature
|
|
doc symbol=SugaredUnion
|
|
body=
|
|
|
|
arg=type
|
|
|
|
feature=union-feat2
|
|
a feature
|
|
doc symbol=Alternate
|
|
body=
|
|
|
|
arg=i
|
|
an integer
|
|
@b is undocumented
|
|
arg=b
|
|
|
|
feature=alt-feat
|
|
a feature
|
|
doc freeform
|
|
body=
|
|
== Another subsection
|
|
doc symbol=cmd
|
|
body=
|
|
|
|
arg=arg1
|
|
the first argument
|
|
arg=arg2
|
|
the second
|
|
argument
|
|
arg=arg3
|
|
|
|
feature=cmd-feat1
|
|
a feature
|
|
feature=cmd-feat2
|
|
another feature
|
|
section=Note
|
|
@arg3 is undocumented
|
|
section=Returns
|
|
@Object
|
|
section=TODO
|
|
frobnicate
|
|
section=Notes
|
|
- Lorem ipsum dolor sit amet
|
|
- Ut enim ad minim veniam
|
|
|
|
Duis aute irure dolor
|
|
section=Example
|
|
-> in
|
|
<- out
|
|
section=Examples
|
|
- *verbatim*
|
|
- {braces}
|
|
section=Since
|
|
2.10
|
|
doc symbol=cmd-boxed
|
|
body=
|
|
If you're bored enough to read this, go see a video of boxed cats
|
|
feature=cmd-feat1
|
|
a feature
|
|
feature=cmd-feat2
|
|
another feature
|
|
section=Example
|
|
-> in
|
|
|
|
<- out
|
|
doc symbol=EVT-BOXED
|
|
body=
|
|
|
|
feature=feat3
|
|
a feature
|