docs/qapidoc: add format_type() method

This method is responsible for generating a type name for a given member
with the correct annotations for the QAPI domain. Features and enums do
not *have* types, so they return None. Everything else returns the type
name with a "?" suffix if that type is optional, and ensconced in
[brackets] if it's an array type.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-47-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index c17cb9f9b16fac58fa1cb1eb68fecc05637ef1fc..5144bb965af6b157e3acc39f2bb847e717564339 100644 (file)
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -40,7 +40,13 @@ from qapi.error import QAPIError
 from qapi.parser import QAPIDoc
 from qapi.schema import (
     QAPISchema,
+    QAPISchemaArrayType,
     QAPISchemaDefinition,
+    QAPISchemaEnumMember,
+    QAPISchemaFeature,
+    QAPISchemaMember,
+    QAPISchemaObjectTypeMember,
+    QAPISchemaType,
     QAPISchemaVisitor,
 )
 from qapi.source import QAPISourceInfo
@@ -58,7 +64,9 @@ if TYPE_CHECKING:
         Any,
         Generator,
         List,
+        Optional,
         Sequence,
+        Union,
     )
 
     from sphinx.application import Sphinx
@@ -128,6 +136,30 @@ class Transmogrifier:
             # +2: correct for zero/one index, then increment by one.
             self.add_line_raw("", fname, line + 2)
 
+    def format_type(
+        self, ent: Union[QAPISchemaDefinition | QAPISchemaMember]
+    ) -> Optional[str]:
+        if isinstance(ent, (QAPISchemaEnumMember, QAPISchemaFeature)):
+            return None
+
+        qapi_type = ent
+        optional = False
+        if isinstance(ent, QAPISchemaObjectTypeMember):
+            qapi_type = ent.type
+            optional = ent.optional
+
+        if isinstance(qapi_type, QAPISchemaArrayType):
+            ret = f"[{qapi_type.element_type.doc_type()}]"
+        else:
+            assert isinstance(qapi_type, QAPISchemaType)
+            tmp = qapi_type.doc_type()
+            assert tmp
+            ret = tmp
+        if optional:
+            ret += "?"
+
+        return ret
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None: