Add type-check annotations to sphinx.util

1 files changed, 21 insertions, 2 deletions

diff --git a/sphinx/util/docfields.py b/sphinx/util/docfields.py
index d5cb4038f..6bf38ebed 100644
--- a/sphinx/util/docfields.py
+++ b/sphinx/util/docfields.py
@@ -15,8 +15,14 @@ from docutils import nodes
 
 from sphinx import addnodes
 
+if False:
+    # For type annotation
+    from typing import Any, Tuple  # NOQA
+    from sphinx.domains import Domain  # NOQA
+
 
 def _is_single_paragraph(node):
+    # type: (nodes.Node) -> bool
     """True if the node only contains one paragraph (and system messages)."""
     if len(node) == 0:
         return False
@@ -47,6 +53,7 @@ class Field(object):
 
     def __init__(self, name, names=(), label=None, has_arg=True, rolename=None,
                  bodyrolename=None):
+        # type: (unicode, Tuple[unicode, ...], unicode, bool, unicode, unicode) -> None
         self.name = name
         self.names = names
         self.label = label
@@ -56,6 +63,7 @@ class Field(object):
 
     def make_xref(self, rolename, domain, target,
                   innernode=addnodes.literal_emphasis, contnode=None):
+        # type: (unicode, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node
         if not rolename:
             return contnode or innernode(target, target)
         refnode = addnodes.pending_xref('', refdomain=domain, refexplicit=False,
@@ -65,12 +73,15 @@ class Field(object):
 
     def make_xrefs(self, rolename, domain, target,
                    innernode=addnodes.literal_emphasis, contnode=None):
+        # type: (unicode, unicode, unicode, nodes.Node, nodes.Node) -> List[nodes.Node]
         return [self.make_xref(rolename, domain, target, innernode, contnode)]
 
     def make_entry(self, fieldarg, content):
+        # type: (List, unicode) -> Tuple[List, unicode]
         return (fieldarg, content)
 
     def make_field(self, types, domain, item):
+        # type: (List, unicode, Tuple) -> nodes.field
         fieldarg, content = item
         fieldname = nodes.field_name('', self.label)
         if fieldarg:
@@ -106,10 +117,12 @@ class GroupedField(Field):
 
     def __init__(self, name, names=(), label=None, rolename=None,
                  can_collapse=False):
+        # type: (unicode, Tuple[unicode, ...], unicode, unicode, bool) -> None
         Field.__init__(self, name, names, label, True, rolename)
         self.can_collapse = can_collapse
 
     def make_field(self, types, domain, items):
+        # type: (List, unicode, Tuple) -> nodes.field
         fieldname = nodes.field_name('', self.label)
         listnode = self.list_type()
         for fieldarg, content in items:
@@ -151,11 +164,13 @@ class TypedField(GroupedField):
 
     def __init__(self, name, names=(), typenames=(), label=None,
                  rolename=None, typerolename=None, can_collapse=False):
+        # type: (unicode, Tuple[unicode, ...], Tuple[unicode, ...], unicode, unicode, unicode, bool) -> None  # NOQA
         GroupedField.__init__(self, name, names, label, rolename, can_collapse)
         self.typenames = typenames
         self.typerolename = typerolename
 
     def make_field(self, types, domain, items):
+        # type: (List, unicode, Tuple) -> nodes.field
         def handle_item(fieldarg, content):
             par = nodes.paragraph()
             par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
@@ -196,6 +211,7 @@ class DocFieldTransformer(object):
     """
 
     def __init__(self, directive):
+        # type: (Any) -> None
         self.domain = directive.domain
         if '_doc_field_type_map' not in directive.__class__.__dict__:
             directive.__class__._doc_field_type_map = \
@@ -203,6 +219,7 @@ class DocFieldTransformer(object):
         self.typemap = directive._doc_field_type_map
 
     def preprocess_fieldtypes(self, types):
+        # type: (List) -> Dict[unicode, Tuple[Any, bool]]
         typemap = {}
         for fieldtype in types:
             for name in fieldtype.names:
@@ -213,6 +230,7 @@ class DocFieldTransformer(object):
         return typemap
 
     def transform_all(self, node):
+        # type: (nodes.Node) -> None
         """Transform all field list children of a node."""
         # don't traverse, only handle field lists that are immediate children
         for child in node:
@@ -220,12 +238,13 @@ class DocFieldTransformer(object):
                 self.transform(child)
 
     def transform(self, node):
+        # type: (nodes.Node) -> None
         """Transform a single field list *node*."""
         typemap = self.typemap
 
         entries = []
-        groupindices = {}
-        types = {}
+        groupindices = {}  # type: Dict[unicode, int]
+        types = {}  # type: Dict[unicode, Dict]
 
         # step 1: traverse all fields and collect field types and content
         for field in node: