[PATCH 06/14] qapi/doc.py: Add type hint annotations

[John Snow]

Annotations do not change runtime behavior.
This commit *only* adds annotations.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 scripts/qapi/doc.py | 119 ++++++++++++++++++++++++++++++++------------
 1 file changed, 87 insertions(+), 32 deletions(-)

diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
index 9a02cf2f27..43943575da 100644
--- a/scripts/qapi/doc.py
+++ b/scripts/qapi/doc.py
@@ -5,14 +5,24 @@
 """This script produces the documentation of a qapi schema in texinfo format"""
 
 import re
-from typing import Optional
+from typing import Callable, List, Optional
 
 from .gen import QAPIGenDoc
+from .parser import QAPIDoc
 from .schema import (
+    QAPISchema,
+    QAPISchemaEntity,
     QAPISchemaEnumMember,
+    QAPISchemaFeature,
+    QAPISchemaMember,
+    QAPISchemaObjectType,
     QAPISchemaObjectTypeMember,
+    QAPISchemaType,
+    QAPISchemaVariants,
     QAPISchemaVisitor,
 )
+from .source import QAPISourceInfo
+
 
 MSG_FMT = """
 @deftypefn {type} {{}} {name}
@@ -36,27 +46,27 @@
 """.format
 
 
-def subst_strong(doc):
+def subst_strong(doc: str) -> str:
     """Replaces *foo* by @strong{foo}"""
     return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc)
 
 
-def subst_emph(doc):
+def subst_emph(doc: str) -> str:
     """Replaces _foo_ by @emph{foo}"""
     return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc)
 
 
-def subst_vars(doc):
+def subst_vars(doc: str) -> str:
     """Replaces @var by @code{var}"""
     return re.sub(r'@([\w-]+)', r'@code{\1}', doc)
 
 
-def subst_braces(doc):
+def subst_braces(doc: str) -> str:
     """Replaces {} with @{ @}"""
     return doc.replace('{', '@{').replace('}', '@}')
 
 
-def texi_example(doc):
+def texi_example(doc: str) -> str:
     """Format @example"""
     # TODO: Neglects to escape @ characters.
     # We should probably escape them in subst_braces(), and rename the
@@ -66,7 +76,7 @@ def texi_example(doc):
     return EXAMPLE_FMT(code=doc)
 
 
-def texi_format(doc):
+def texi_format(doc: str) -> str:
     """
     Format documentation
 
@@ -126,19 +136,26 @@ def texi_format(doc):
     return ret
 
 
-def texi_body(doc):
+def texi_body(doc: QAPIDoc) -> str:
     """Format the main documentation body"""
     return texi_format(doc.body.text)
 
 
-def texi_if(ifcond, prefix='\n', suffix='\n'):
+def texi_if(ifcond: Optional[List[str]],
+            prefix: str = '\n',
+            suffix: str = '\n') -> str:
     """Format the #if condition"""
     if not ifcond:
         return ''
     return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix)
 
 
-def texi_enum_value(value, desc, suffix):
+TexiMemberCallback = Callable[[QAPISchemaMember, str, str], str]
+
+
+def texi_enum_value(value: QAPISchemaMember,
+                    desc: str,
+                    suffix: str) -> str:
     """Format a table of members item for an enumeration value"""
     assert isinstance(value, QAPISchemaEnumMember)
     assert suffix == '', "Ignored suffix for texi_enum_value"
@@ -146,7 +163,9 @@ def texi_enum_value(value, desc, suffix):
         value.name, desc, texi_if(value.ifcond, prefix='@*'))
 
 
-def texi_member(member, desc, suffix):
+def texi_member(member: QAPISchemaMember,
+                desc: str,
+                suffix: str) -> str:
     """Format a table of members item for an object type member"""
     assert isinstance(member, QAPISchemaObjectTypeMember)
     typ = member.type.doc_type()
@@ -157,8 +176,11 @@ def texi_member(member, desc, suffix):
         suffix, desc, texi_if(member.ifcond, prefix='@*'))
 
 
-def texi_members(doc, what, base=None, variants=None,
-                 member_func=texi_member):
+def texi_members(doc: QAPIDoc,
+                 what: str,
+                 base: Optional[QAPISchemaObjectType] = None,
+                 variants: Optional[QAPISchemaVariants] = None,
+                 member_func: TexiMemberCallback = texi_member) -> str:
     """Format the table of members"""
     items = ''
     for section in doc.args.values():
@@ -195,7 +217,8 @@ def texi_members(doc, what, base=None, variants=None,
     return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items)
 
 
-def texi_arguments(doc, boxed_arg_type):
+def texi_arguments(doc: QAPIDoc,
+                   boxed_arg_type: Optional[QAPISchemaObjectType]) -> str:
     if boxed_arg_type:
         assert not doc.args
         return ('\n@b{Arguments:} the members of @code{%s}\n'
@@ -203,7 +226,7 @@ def texi_arguments(doc, boxed_arg_type):
     return texi_members(doc, 'Arguments')
 
 
-def texi_features(doc):
+def texi_features(doc: QAPIDoc) -> str:
     """Format the table of features"""
     items = ''
     for section in doc.features.values():
@@ -214,7 +237,7 @@ def texi_features(doc):
     return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items)
 
 
-def texi_sections(doc, ifcond):
+def texi_sections(doc: QAPIDoc, ifcond: Optional[List[str]]) -> str:
     """Format additional sections following arguments"""
     body = ''
     for section in doc.sections:
@@ -229,7 +252,7 @@ def texi_sections(doc, ifcond):
     return body
 
 
-def texi_type(typ, doc, ifcond, members):
+def texi_type(typ: str, doc: QAPIDoc, ifcond: List[str], members: str) -> str:
     return TYPE_FMT(type=typ,
                     name=doc.symbol,
                     body=texi_body(doc),
@@ -238,7 +261,7 @@ def texi_type(typ, doc, ifcond, members):
                     sections=texi_sections(doc, ifcond))
 
 
-def texi_msg(typ, doc, ifcond, members):
+def texi_msg(typ: str, doc: QAPIDoc, ifcond: List[str], members: str) -> str:
     return MSG_FMT(type=typ,
                    name=doc.symbol,
                    body=texi_body(doc),
@@ -248,60 +271,92 @@ def texi_msg(typ, doc, ifcond, members):
 
 
 class QAPISchemaGenDocVisitor(QAPISchemaVisitor):
-    def __init__(self, prefix):
+    def __init__(self, prefix: str):
         self._prefix = prefix
         self._gen = QAPIGenDoc(self._prefix + 'qapi-doc.texi')
-        self.cur_doc = None
+        self.cur_doc: Optional[QAPIDoc] = None
 
-    def write(self, output_dir):
+    def write(self, output_dir: str) -> None:
         self._gen.write(output_dir)
 
-    def visit_enum_type(self, name, info, ifcond, features, members, prefix):
+    def visit_enum_type(self,
+                        name: str,
+                        info: QAPISourceInfo,
+                        ifcond: List[str],
+                        features: List[QAPISchemaFeature],
+                        members: List[QAPISchemaEnumMember],
+                        prefix: Optional[str]) -> None:
         doc = self.cur_doc
         self._gen.add(texi_type('Enum', doc, ifcond,
                                 texi_members(doc, 'Values',
                                              member_func=texi_enum_value)))
 
-    def visit_object_type(self, name, info, ifcond, features,
-                          base, members, variants):
+    def visit_object_type(self,
+                          name: str,
+                          info: QAPISourceInfo,
+                          ifcond: List[str],
+                          features: List[QAPISchemaFeature],
+                          base: Optional[QAPISchemaObjectType],
+                          members: List[QAPISchemaObjectTypeMember],
+                          variants: Optional[QAPISchemaVariants]) -> None:
         doc = self.cur_doc
         if base and base.is_implicit():
             base = None
         self._gen.add(texi_type('Object', doc, ifcond,
                                 texi_members(doc, 'Members', base, variants)))
 
-    def visit_alternate_type(self, name, info, ifcond, features, variants):
+    def visit_alternate_type(self,
+                             name: str,
+                             info: QAPISourceInfo,
+                             ifcond: List[str],
+                             features: List[QAPISchemaFeature],
+                             variants: QAPISchemaVariants) -> None:
         doc = self.cur_doc
         self._gen.add(texi_type('Alternate', doc, ifcond,
                                 texi_members(doc, 'Members')))
 
-    def visit_command(self, name, info, ifcond, features,
-                      arg_type, ret_type, gen, success_response, boxed,
-                      allow_oob, allow_preconfig):
+    def visit_command(self,
+                      name: str,
+                      info: QAPISourceInfo,
+                      ifcond: List[str],
+                      features: List[QAPISchemaFeature],
+                      arg_type: QAPISchemaObjectType,
+                      ret_type: QAPISchemaType,
+                      gen: bool,
+                      success_response: bool,
+                      boxed: bool,
+                      allow_oob: bool,
+                      allow_preconfig: bool) -> None:
         doc = self.cur_doc
         members = texi_arguments(doc, arg_type if boxed else None)
         self._gen.add(texi_msg('Command', doc, ifcond, members))
 
-    def visit_event(self, name, info, ifcond, features, arg_type, boxed):
+    def visit_event(self,
+                    name: str,
+                    info: QAPISourceInfo,
+                    ifcond: List[str],
+                    features: List[QAPISchemaFeature],
+                    arg_type: QAPISchemaObjectType,
+                    boxed: bool) -> None:
         doc = self.cur_doc
         members = texi_arguments(doc, arg_type if boxed else None)
         self._gen.add(texi_msg('Event', doc, ifcond, members))
 
-    def symbol(self, doc, entity):
+    def symbol(self, doc: QAPIDoc, entity: QAPISchemaEntity) -> None:
         if self._gen._body:
             self._gen.add('\n')
         self.cur_doc = doc
         entity.visit(self)
         self.cur_doc = None
 
-    def freeform(self, doc):
+    def freeform(self, doc: QAPIDoc) -> None:
         assert not doc.args
         if self._gen._body:
             self._gen.add('\n')
         self._gen.add(texi_body(doc) + texi_sections(doc, None))
 
 
-def gen_doc(schema, output_dir, prefix):
+def gen_doc(schema: QAPISchema, output_dir: str, prefix: str) -> None:
     vis = QAPISchemaGenDocVisitor(prefix)
     vis.visit_begin(schema)
     for doc in schema.docs:
-- 
2.26.2