From f1a787b5f4b60524580ed9d1527568590d73789b Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 25 Apr 2023 08:42:13 +0200 Subject: qapi: @foo should be used to reference, not ``foo`` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documentation suggests @foo is merely shorthand for ``foo``. It's not, it carries additional meaning: it's a reference to a QAPI schema name. Reword the documentation to spell that out. Fix up the few ``foo`` that should be @foo. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-André Lureau Message-Id: <20230425064223.820979-7-armbru@redhat.com> --- docs/devel/qapi-code-gen.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 879a649..d81aac7 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -924,9 +924,11 @@ first character of the first line. The usual ****strong****, *\*emphasized\** and ````literal```` markup should be used. If you need a single literal ``*``, you will need to -backslash-escape it. As an extension beyond the usual rST syntax, you -can also use ``@foo`` to reference a name in the schema; this is rendered -the same way as ````foo````. +backslash-escape it. + +Use ``@foo`` to reference a name in the schema. This is an rST +extension. It is rendered the same way as ````foo````, but carries +additional meaning. Example:: -- cgit v1.1 From c11010289851ab1943442ff87cf19b7686fb94b3 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 25 Apr 2023 08:42:16 +0200 Subject: qapi: Fix bullet list markup in documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Peter Maydell's commit 100cc4fe0f08 explains: rST insists on a blank line before and after a bulleted list [...] Add some extra blank lines in the doc comments so they're acceptable rST input. It missed one in qapi/trace.json. Paolo Bonzini later added another instance in qapi/stats.json, providing further, if unintended, evidence for his quip that rST is the Perl of ASCII-based markups. Both are parsed as ordinary paragraph, resulting in garbled output. John Snow missed the need for a blank line when converting docs/devel/qapi-code-gen.txt to rST. Add the blank lines we need to get the bullet lists recognized as such. Kevin Wolf and Lukas Straub added two more, but indented. Sphinx recognizes them as (indented) bullet lists. The indentation looks slightly off. Insert a blank line and delete the extra indentation. Fixes: 100cc4fe0f0827f8da1a5c05f9c65e2aaa40e03d (qapi: Add blank lines before bulleted lists) Fixes: 467ef823d83e (qmp: add filtering of statistics by target vCPU) Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Reviewed-by: Marc-André Lureau Message-Id: <20230425064223.820979-10-armbru@redhat.com> [Fix of docs/devel/qapi-code-gen.rst squashed, commit message adjusted] --- docs/devel/qapi-code-gen.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index d81aac7..ea05920 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -934,6 +934,7 @@ Example:: ## # Some text foo with **bold** and *emphasis* + # # 1. with a list # 2. like that # -- cgit v1.1 From e2e9e567f0e23971cac35ba1dee7edb51085b5f7 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 27 Apr 2023 11:53:45 +0200 Subject: docs/devel/qapi-code-gen: Describe some doc markup pitfalls Signed-off-by: Markus Armbruster Message-Id: <20230427095346.1238913-1-armbru@redhat.com> Reviewed-by: Juan Quintela Reviewed-by: Vladimir Sementsov-Ogievskiy --- docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) (limited to 'docs/devel') diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ea05920..af1986f 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1060,6 +1060,59 @@ For example:: 'returns': ['BlockStats'] } +Markup pitfalls +~~~~~~~~~~~~~~~ + +A blank line is required between list items and paragraphs. Without +it, the list may not be recognized, resulting in garbled output. Good +example:: + + # An event's state is modified if: + # + # - its name matches the @name pattern, and + # - if @vcpu is given, the event has the "vcpu" property. + +Without the blank line this would be a single paragraph. + +Indentation matters. Bad example:: + + # @none: None (no memory side cache in this proximity domain, + # or cache associativity unknown) + +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)". + +Section tags are case-sensitive and end with a colon. Good example:: + + # Since: 7.1 + +Bad examples (all ordinary paragraphs):: + + # since: 7.1 + + # Since 7.1 + + # Since : 7.1 + +Likewise, member descriptions require a colon. Good example:: + + # @interface-id: Interface ID + +Bad examples (all ordinary paragraphs):: + + # @interface-id Interface ID + + # @interface-id : Interface ID + +Undocumented members are not flagged, yet. Instead, the generated +documentation describes them as "Not documented". Think twice before +adding more undocumented members. + +When you change documentation comments, please check the generated +documentation comes out as intended! + + Client JSON Protocol introspection ================================== -- cgit v1.1