diff options
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 48 |
1 files changed, 23 insertions, 25 deletions
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 875f893..5618a80 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -947,6 +947,11 @@ Example:: # <- get that ## +For legibility, wrap text paragraphs so every line is at most 70 +characters long. + +Separate sentences with two spaces. + Definition documentation ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -963,22 +968,12 @@ commands and events), member (for structs and unions), branch (for alternates), or value (for enums), a description of each feature (if any), and finally optional tagged sections. -The description of an argument or feature 'name' starts with -'\@name:'. The description text can start on the line following the -'\@name:', in which case it must not be indented at all. It can also -start on the same line as the '\@name:'. In this case if it spans -multiple lines then second and subsequent lines must be indented to -line up with the first character of the first line of the -description:: - - # @argone: - # This is a two line description - # in the first style. - # - # @argtwo: This is a two line description - # in the second style. +Descriptions start with '\@name:'. The description text should be +indented like this:: + + # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed + # do eiusmod tempor incididunt ut labore et dolore magna aliqua. -The number of spaces between the ':' and the text is not significant. .. FIXME The parser accepts these things in almost any order. .. FIXME union branches should be described, too. @@ -990,23 +985,26 @@ The feature descriptions must be preceded by a line "Features:", like this:: # Features: + # # @feature: Description text A tagged section starts with one of the following words: "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". The section ends with the start of a new section. -The text of a section can start on a new line, in -which case it must not be indented at all. It can also start -on the same line as the "Note:", "Returns:", etc tag. In this -case if it spans multiple lines then second and subsequent -lines must be indented to match the first, in the same way as -multiline argument descriptions. +The second and subsequent lines of sections other than +"Example"/"Examples" should be indented like this:: + + # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco + # laboris nisi ut aliquip ex ea commodo consequat. + # + # Duis aute irure dolor in reprehenderit in voluptate velit esse + # cillum dolore eu fugiat nulla pariatur. A "Since: x.y.z" tagged section lists the release that introduced the definition. -An "Example" or "Examples" section is automatically rendered entirely +An "Example" or "Examples" section is rendered entirely as literal fixed-width text. "TODO" sections are not rendered at all (they are for developers, not users of QMP). In other sections, the text is formatted, and rST markup can be used. @@ -1019,7 +1017,7 @@ For example:: # Statistics of a virtual block device or a block backing device. # # @device: If the stats are for a virtual block device, the name - # corresponding to the virtual block device. + # corresponding to the virtual block device. # # @node-name: The node name of the device. (since 2.3) # @@ -1036,8 +1034,8 @@ For example:: # # Query the @BlockStats for all virtual block devices. # - # @query-nodes: If true, the command will query all the - # block nodes ... explain, explain ... (since 2.3) + # @query-nodes: If true, the command will query all the block nodes + # ... explain, explain ... (since 2.3) # # Returns: A list of @BlockStats for each virtual block devices. # |