``:error: descr`` can now be used to document error conditions. The
format of the description is not defined here; so the ability to name
specific types is left to the document writer.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapi_domain.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index e1b766d9481..d60cccb8e95 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -35,7 +35,7 @@
 from sphinx.locale import _, __
 from sphinx.roles import XRefRole
 from sphinx.util import logging
-from sphinx.util.docfields import GroupedField, TypedField
+from sphinx.util.docfields import Field, GroupedField, TypedField
 from sphinx.util.docutils import SphinxDirective
 from sphinx.util.nodes import make_id, make_refnode
 
@@ -285,6 +285,13 @@ class QAPICommand(QAPIObject):
                 names=("arg",),
                 can_collapse=False,
             ),
+            # :error: descr
+            Field(
+                "error",
+                label=_("Errors"),
+                names=("error", "errors"),
+                has_arg=False,
+            ),
         ]
     )
 
-- 
2.48.1

John Snow <jsnow@redhat.com> writes:

> ``:error: descr`` can now be used to document error conditions. The
> format of the description is not defined here; so the ability to name
> specific types is left to the document writer.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

By convention, the description is a bullet list, but we don't enforce
that in software.  Observation, not a suggestion to start enforcing it
now.

On Fri, Mar 7, 2025 at 2:48 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > ``:error: descr`` can now be used to document error conditions. The
> > format of the description is not defined here; so the ability to name
> > specific types is left to the document writer.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> By convention, the description is a bullet list, but we don't enforce
> that in software.  Observation, not a suggestion to start enforcing it
> now.
>

Right. This commit message is accurate, though: this field list type will
accept any old thing. I have an idea to fix this to make the aesthetics
better (fixes the misalignment) and to enforce the bulleted list in one
shot. Not for this series, sorry. Please accept a raincheck.

John Snow <jsnow@redhat.com> writes:

> On Fri, Mar 7, 2025 at 2:48 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > ``:error: descr`` can now be used to document error conditions. The
>> > format of the description is not defined here; so the ability to name
>> > specific types is left to the document writer.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>>
>> By convention, the description is a bullet list, but we don't enforce
>> that in software.  Observation, not a suggestion to start enforcing it
>> now.
>>
>
> Right. This commit message is accurate, though: this field list type will
> accept any old thing. I have an idea to fix this to make the aesthetics
> better (fixes the misalignment) and to enforce the bulleted list in one
> shot. Not for this series, sorry. Please accept a raincheck.

You're quite right to resist mission creep.

The commit message could mention the convention, say "The format of the
description is not defined here (we make it a bulleted list, but that's
just convention); ..."  Up to you.