Docstring cleanups

src/hawkmoth/docstring.py

@@ -64,12 +64,6 @@ def __init__(self, domain='c', text=None, name=None,
         self._domain = domain
         self._children = []
 
-    def add_child(self, comment):
-        self._children.append(comment)
-
-    def add_children(self, comments):
-        self._children.extend(comments)
-
     def _match(self, filter_types=None, filter_names=None):
         if filter_types is not None and type(self) not in filter_types:
             return False
@@ -80,23 +74,9 @@ def _match(self, filter_types=None, filter_names=None):
         return True
 
     def walk(self, recurse=True, filter_types=None, filter_names=None):
-        # Note: The filtering is pretty specialized for our use case here. It
-        # only filters the immediate children, not this comment, nor
-        # grandchildren.
-
-        # The contents of the parent will always be before children.
         if self._text:
             yield self
 
-        # Sort the children by order of appearance. We may add other sort
-        # options later.
-        for comment in sorted(self._children, key=lambda c: c.get_line()):
-            if comment._match(filter_types=filter_types, filter_names=filter_names):
-                if recurse:
-                    yield from comment.walk()
-                else:
-                    yield comment
-
     @staticmethod
     def is_doc(comment):
         """Test if comment is a C documentation comment."""
@@ -173,10 +153,19 @@ def get_docstring(self, process_docstring=None):
 
         Docstring._nest(comment_lines, self._indent)
 
+        # ensure we have cushion blank line before the docstring
+        if len(header_lines) == 0 or header_lines[0] != '':
+            header_lines.insert(0, '')
+
+        # ensure we have cushion blank line between header and comment
+        if header_lines[-1] != '':
+            header_lines.append('')
+
         lines = header_lines + comment_lines
 
         Docstring._nest(lines, self._nest)
 
+        # ensure we have cushion blank line after the docstring
         if lines[-1] != '':
             lines.append('')
 
@@ -194,24 +183,9 @@ def get_name(self):
     def get_line(self):
         return self._meta['line']
 
-class RootDocstring(Docstring):
-    def __init__(self, filename=None, domain='c', clang_args=None):
-        super().__init__(domain=domain)
-        self._filename = filename
-        self._clang_args = clang_args
-
-    def get_filename(self):
-        return self._filename
-
-    def get_clang_args(self):
-        return self._clang_args
-
-    def get_domain(self):
-        return self._domain
-
 class TextDocstring(Docstring):
     _indent = 0
-    _fmt = '\n'
+    _fmt = ''
 
     def get_name(self):
         """Figure out a name for the text comment based on the comment contents.
@@ -244,11 +218,11 @@ def get_name(self):
 
 class VarDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. {domain}:var:: {ttype}{type_spacer}{name}\n\n'
+    _fmt = '.. {domain}:var:: {ttype}{type_spacer}{name}'
 
 class TypeDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. {domain}:type:: {name}\n\n'
+    _fmt = '.. {domain}:type:: {name}'
 
 class _CompoundDocstring(Docstring):
     def _get_decl_name(self):
@@ -262,21 +236,60 @@ def _get_decl_name(self):
 
         return self._decl_name
 
+    def add_child(self, comment):
+        self._children.append(comment)
+
+    def add_children(self, comments):
+        self._children.extend(comments)
+
+    def walk(self, recurse=True, filter_types=None, filter_names=None):
+        # Note: The filtering is pretty specialized for our use case here. It
+        # only filters the immediate children, not this comment, nor
+        # grandchildren.
+
+        # The contents of the parent will always be before children.
+        if self._text:
+            yield self
+
+        # Sort the children by order of appearance. We may add other sort
+        # options later.
+        for comment in sorted(self._children, key=lambda c: c.get_line()):
+            if comment._match(filter_types=filter_types, filter_names=filter_names):
+                if recurse:
+                    yield from comment.walk()
+                else:
+                    yield comment
+
+class RootDocstring(_CompoundDocstring):
+    def __init__(self, filename=None, domain='c', clang_args=None):
+        super().__init__(domain=domain)
+        self._filename = filename
+        self._clang_args = clang_args
+
+    def get_filename(self):
+        return self._filename
+
+    def get_clang_args(self):
+        return self._clang_args
+
+    def get_domain(self):
+        return self._domain
+
 class StructDocstring(_CompoundDocstring):
     _indent = 1
-    _fmt = '\n.. {domain}:struct:: {name}\n\n'
+    _fmt = '.. {domain}:struct:: {name}'
 
 class UnionDocstring(_CompoundDocstring):
     _indent = 1
-    _fmt = '\n.. {domain}:union:: {name}\n\n'
+    _fmt = '.. {domain}:union:: {name}'
 
 class EnumDocstring(_CompoundDocstring):
     _indent = 1
-    _fmt = '\n.. {domain}:enum:: {name}\n\n'
+    _fmt = '.. {domain}:enum:: {name}'
 
 class EnumeratorDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. {domain}:enumerator:: {name}{value}\n\n'
+    _fmt = '.. {domain}:enumerator:: {name}{value}'
 
     def __init__(self, domain, name, value, text, meta, nest):
         self._value = value
@@ -291,24 +304,24 @@ def _get_header_lines(self):
 
 class MemberDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. {domain}:member:: {ttype}{type_spacer}{name}\n\n'
+    _fmt = '.. {domain}:member:: {ttype}{type_spacer}{name}'
 
 class MacroDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. c:macro:: {name}\n\n'
+    _fmt = '.. c:macro:: {name}'
 
 class MacroFunctionDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. c:macro:: {name}({args})\n\n'
+    _fmt = '.. c:macro:: {name}({args})'
 
 class FunctionDocstring(Docstring):
     _indent = 1
-    _fmt = '\n.. {domain}:function:: {ttype}{type_spacer}{name}({args}){quals_spacer}{quals}\n\n'
+    _fmt = '.. {domain}:function:: {ttype}{type_spacer}{name}({args}){quals_spacer}{quals}'
 
 class ClassDocstring(_CompoundDocstring):
     _indent = 1
-    _fmt = '\n.. cpp:class:: {name}\n\n'
+    _fmt = '.. cpp:class:: {name}'
 
-class EnumClassDocstring(Docstring):
+class EnumClassDocstring(_CompoundDocstring):
     _indent = 1
-    _fmt = '\n.. cpp:enum-class:: {name}\n\n'
+    _fmt = '.. cpp:enum-class:: {name}'