[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 17/17] docs/devel/qapi-code-gen: Describe some doc markup pitfalls
From: |
Markus Armbruster |
Subject: |
[PULL 17/17] docs/devel/qapi-code-gen: Describe some doc markup pitfalls |
Date: |
Fri, 28 Apr 2023 12:29:01 +0200 |
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230427095346.1238913-1-armbru@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
---
docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++
1 file changed, 53 insertions(+)
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index ea0592034a..af1986f33e 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
==================================
--
2.39.2
- [PULL 01/17] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status, (continued)
- [PULL 01/17] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status, Markus Armbruster, 2023/04/28
- [PULL 15/17] qapi: Format since information the conventional way: (since X.Y), Markus Armbruster, 2023/04/28
- [PULL 05/17] qapi/block-core: Clean up after removal of dirty bitmap @status, Markus Armbruster, 2023/04/28
- [PULL 13/17] qapi: Replace ad hoc "since" documentation by member documentation, Markus Armbruster, 2023/04/28
- [PULL 16/17] qapi storage-daemon/qapi: Fix documentation section structure, Markus Armbruster, 2023/04/28
- [PULL 08/17] qapi: Delete largely misleading "Stability Considerations", Markus Armbruster, 2023/04/28
- [PULL 14/17] qapi: Fix misspelled section tags in doc comments, Markus Armbruster, 2023/04/28
- [PULL 07/17] qapi: Tidy up examples, Markus Armbruster, 2023/04/28
- [PULL 02/17] qga/qapi-schema: Fix a misspelled reference, Markus Armbruster, 2023/04/28
- [PULL 11/17] qga/qapi-schema: Fix member documentation markup, Markus Armbruster, 2023/04/28
- [PULL 17/17] docs/devel/qapi-code-gen: Describe some doc markup pitfalls,
Markus Armbruster <=
- [PULL 10/17] qapi: Fix unintended definition lists in documentation, Markus Armbruster, 2023/04/28
- Re: [PULL 00/17] QAPI patches patches for 2023-04-28, Richard Henderson, 2023/04/29