dfaggioli/qemu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

qapi: New documentation section tag "Errors"

Browse Source 
We use section "Returns" for documenting both success and error
response of commands.

I intend to generate better command success response documentation.
Easier when "Returns" documents just he success response.

Create new section tag "Errors".  The next two commits will move error
response documentation from "Returns" sections to "Errors" sections.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-4-armbru@redhat.com>
This commit is contained in:
Markus Armbruster
2024-02-27 12:39:11 +01:00
parent 51e97c14fb
commit 3a025d3d1f
5 changed files with 32 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/devel/qapi-code-gen.rst
View File

@@ -996,7 +996,8 @@ line "Features:", like this::
A tagged section begins with a paragraph that starts with one of the
following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:",
"Returns:", "TODO:". It ends with the start of a new section.
"Returns:", "Errors:", "TODO:". It ends with the start of a new
section.
The second and subsequent lines of tagged sections must be indented
like this::
@@ -1007,6 +1008,9 @@ like this::
# Duis aute irure dolor in reprehenderit in voluptate velit esse
# cillum dolore eu fugiat nulla pariatur.
"Returns" and "Errors" sections are only valid for commands. They
document the success and the error response, respectively.
A "Since: x.y.z" tagged section lists the release that introduced the
definition.