From 0c7811aeb9ba206a74008ca28f5b8ff8e7f74d04 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 28 Apr 2023 12:54:13 +0200 Subject: docs/devel/qapi-code-gen: Clean up use of quotes a bit Section "Definition documentation" uses both single and double quotes around doc text snippets. Stick to double quotes. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-2-armbru@redhat.com> Reviewed-by: Juan Quintela --- docs/devel/qapi-code-gen.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index af1986f..289869c 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -989,7 +989,7 @@ The number of spaces between the ':' and the text is not significant. union branches should be described, too. Extensions added after the definition was first released carry a -'(since x.y.z)' comment. +"(since x.y.z)" comment. The feature descriptions must be preceded by a line "Features:", like this:: @@ -1003,17 +1003,17 @@ 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 +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. -A 'Since: x.y.z' tagged section lists the release that introduced the +A "Since: x.y.z" tagged section lists the release that introduced the definition. -An 'Example' or 'Examples' section is automatically rendered -entirely as literal fixed-width text. In other sections, -the text is formatted, and rST markup can be used. +An "Example" or "Examples" section is automatically rendered entirely +as literal fixed-width text. In other sections, the text is +formatted, and rST markup can be used. For example:: -- cgit v1.1 From a2836b32b02a1d774f8c2504cb368c05d74ad492 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 28 Apr 2023 12:54:14 +0200 Subject: docs/devel/qapi-code-gen: Turn FIXME admonitions into comments We have two FIXME notes. These FIXMEs are for QAPI developers. They are not useful for QAPI schema developers. They are marked up as admonitions, which makes them look important in generated HTML. Turn them into comments. QAPI developers will still see them (they read and write the .rst). QAPI schema developers may still see them (if they read the .rst instead of the generated .html), but "this is just for QAPI developers" should be more obvious. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-3-armbru@redhat.com> Reviewed-by: Juan Quintela --- docs/devel/qapi-code-gen.rst | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 289869c..ff7b74b 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -979,14 +979,9 @@ description:: # in the second style. The number of spaces between the ':' and the text is not significant. +.. FIXME The parser accepts these things in almost any order. -.. admonition:: FIXME - - The parser accepts these things in almost any order. - -.. admonition:: FIXME - - union branches should be described, too. +.. FIXME union branches should be described, too. Extensions added after the definition was first released carry a "(since x.y.z)" comment. -- cgit v1.1 From f57e1d05bfaf2f41f0793280886ebf1db753794f Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 28 Apr 2023 12:54:18 +0200 Subject: sphinx/qapidoc: Do not emit TODO sections into user manuals QAPI doc comments are for QMP users: they go into the "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual". The doc comment TODO sections are for somebody else, namely for the people who can do: developers. Do not emit them into the user manuals. This elides the following TODOs: * SchemaInfoCommand # TODO: @success-response (currently irrelevant, because it's QGA, not QMP) This is a note to developers adding introspection to the guest agent. It makes no sense to users. * @query-hotpluggable-cpus # TODO: Better documentation; currently there is none. This is a reminder for developers. It doesn't help users. * @device_add # TODO: This command effectively bypasses QAPI completely due to its # "additional arguments" business. It shouldn't have been added to # the schema in this form. It should be qapified properly, or # replaced by a properly qapified command. Likewise. Eliding them is an improvement. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-7-armbru@redhat.com> Reviewed-by: Ani Sinha Reviewed-by: Juan Quintela --- docs/devel/qapi-code-gen.rst | 5 +++-- docs/sphinx/qapidoc.py | 3 +++ 2 files changed, 6 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ff7b74b..6386b58 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1007,8 +1007,9 @@ A "Since: x.y.z" tagged section lists the release that introduced the definition. An "Example" or "Examples" section is automatically rendered entirely -as literal fixed-width text. In other sections, the text is -formatted, and rST markup can be used. +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. For example:: diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d791b59..8f3b999 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -268,6 +268,9 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): """Return list of doctree nodes for additional sections""" nodelist = [] for section in doc.sections: + if section.name and section.name == 'TODO': + # Hide TODO: sections + continue snode = self._make_section(section.name) if section.name and section.name.startswith('Example'): snode += self._nodes_for_example(section.text) -- cgit v1.1 From 08349786c84306863a3b659c8a9b28bb74c405c6 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 28 Apr 2023 12:54:25 +0200 Subject: qapi: Relax doc string @name: description indentation rules The QAPI schema doc comment language provides special syntax for command and event arguments, struct and union members, alternate branches, enumeration values, and features: descriptions starting with "@name:". By convention, we format them like this: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, # sed do eiusmod tempor incididunt ut labore et dolore # magna aliqua. Okay for names as short as "name", but we have much longer ones. Their description gets squeezed against the right margin, like this: # @dirty-sync-missed-zero-copy: Number of times dirty RAM synchronization could # not avoid copying dirty pages. This is between # 0 and @dirty-sync-count * @multifd-channels. # (since 7.1) The description text is effectively just 50 characters wide. Easy enough to read, but can be cumbersome to write. The awkward squeeze against the right margin makes people go beyond it, which produces two undesirables: arguments about style, and descriptions that are unnecessarily hard to read, like this one: # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. This is # only present when the postcopy-blocktime migration capability # is enabled. (Since 3.0) We could instead format it like # @postcopy-vcpu-blocktime: # list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0) or, since the commit before previous, like # @postcopy-vcpu-blocktime: # list of the postcopy blocktime per vCPU. This is only present # when the postcopy-blocktime migration capability is # enabled. (Since 3.0) However, I'd rather have # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU. # This is only present when the postcopy-blocktime migration # capability is enabled. (Since 3.0) because this is how rST field and option lists work. To get this, we need to let the first non-blank line after the "@name:" line determine expected indentation. This fills up the indentation pitfall mentioned in docs/devel/qapi-code-gen.rst. A related pitfall still exists. Update the text to show it. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-14-armbru@redhat.com> Reviewed-by: Juan Quintela [Work around lack of walrus operator in Python 3.7 and older] --- docs/devel/qapi-code-gen.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 6386b58..875f893 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1074,10 +1074,14 @@ Indentation matters. Bad example:: # @none: None (no memory side cache in this proximity domain, # or cache associativity unknown) + # (since 5.0) -The description is parsed as a definition list with term "None (no -memory side cache in this proximity domain," and definition "or cache -associativity unknown)". +The last line's de-indent is wrong. The second and subsequent lines +need to line up with each other, like this:: + + # @none: None (no memory side cache in this proximity domain, + # or cache associativity unknown) + # (since 5.0) Section tags are case-sensitive and end with a colon. Good example:: -- cgit v1.1 From 9d167491cb2577d0d9394624b41a77ef709e4336 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 28 Apr 2023 12:54:27 +0200 Subject: docs/devel/qapi-code-gen: Update doc comment conventions The commit before previous relaxed the indentation rules to let us improve the doc comment conventions. This commit changes the written conventions. The next commits will update QAPI schemas to conform to them. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-16-armbru@redhat.com> Reviewed-by: Juan Quintela --- docs/devel/qapi-code-gen.rst | 48 +++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 25 deletions(-) (limited to 'docs') 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. # -- cgit v1.1