[hawkmoth] [PATCH 08/11] parser: start using c:struct, c:union, and c:enum directives

  • From: Jani Nikula <jani@xxxxxxxxxx>
  • To: hawkmoth@xxxxxxxxxxxxx
  • Date: Tue, 15 Dec 2020 21:00:05 +0200

From: Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>

All the new domains are purely cosmetic changes, but some of them are
indeed nicer. We implement some of them here.

This breaks compatibility with Sphinx 2 which does not provide any of
the new directives.

[Jani: Fix name to be as required by sphinx, squash the test changes,
and rewrite commit message.]
---
 hawkmoth/parser.py         | 12 +++++++++---
 hawkmoth/util/docstr.py    |  6 ++++++
 test/enum.rst              |  2 +-
 test/example-40-enum.rst   |  2 +-
 test/example-50-struct.rst |  2 +-
 test/struct.rst            |  2 +-
 test/typedef-enum.rst      |  4 ++--
 test/typedef-struct.rst    |  4 ++--
 test/union.rst             |  4 ++--
 9 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/hawkmoth/parser.py b/hawkmoth/parser.py
index 83b67c00d4ec..37862d38327c 100644
--- a/hawkmoth/parser.py
+++ b/hawkmoth/parser.py
@@ -1,5 +1,5 @@
 # Copyright (c) 2016-2017 Jani Nikula <jani@xxxxxxxxxx>
-# Copyright (c) 2018-2019 Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
+# Copyright (c) 2018-2020 Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
 # Licensed under the terms of BSD 2-Clause, see LICENSE for details.
 """
 Documentation comment extractor
@@ -199,9 +199,15 @@ def _recursive_parse(comments, cursor, nest, compat):
 
         # FIXME: Handle anonymous enumerators.
 
-        fmt = docstr.Type.TYPE
+        fmts = {CursorKind.STRUCT_DECL: docstr.Type.STRUCT,
+                CursorKind.UNION_DECL: docstr.Type.UNION,
+                CursorKind.ENUM_DECL: docstr.Type.ENUM}
+
+        fmt = fmts[cursor.kind]
+
+        # name may be empty for typedefs
         result = _result(comment, cursor=cursor, fmt=fmt,
-                         nest=nest, name=ttype, compat=compat)
+                         nest=nest, name=name if name else ttype, 
compat=compat)
 
         nest += 1
         for c in cursor.get_children():
diff --git a/hawkmoth/util/docstr.py b/hawkmoth/util/docstr.py
index ca3faa9a5801..92b14d615ef3 100644
--- a/hawkmoth/util/docstr.py
+++ b/hawkmoth/util/docstr.py
@@ -17,6 +17,9 @@ class Type(Enum):
     TEXT = auto()
     VAR = auto()
     TYPE = auto()
+    STRUCT = auto()
+    UNION = auto()
+    ENUM = auto()
     ENUM_VAL = auto()
     MEMBER = auto()
     MACRO = auto()
@@ -31,6 +34,9 @@ _doc_fmt = {
     Type.TEXT:       (0, '\n{text}\n'),
     Type.VAR:        (1, '\n.. c:var:: {ttype} {name}\n\n{text}\n'),
     Type.TYPE:       (1, '\n.. c:type:: {name}\n\n{text}\n'),
+    Type.STRUCT:     (1, '\n.. c:struct:: {name}\n\n{text}\n'),
+    Type.UNION:      (1, '\n.. c:union:: {name}\n\n{text}\n'),
+    Type.ENUM:       (1, '\n.. c:enum:: {name}\n\n{text}\n'),
     Type.ENUM_VAL:   (1, '\n.. c:enumerator:: {name}\n\n{text}\n'),
     Type.MEMBER:     (1, '\n.. c:member:: {ttype} {name}\n\n{text}\n'),
     Type.MACRO:      (1, '\n.. c:macro:: {name}\n\n{text}\n'),
diff --git a/test/enum.rst b/test/enum.rst
index 5d939ef77be3..65f72abf7f8c 100644
--- a/test/enum.rst
+++ b/test/enum.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: enum foo
+.. c:enum:: foo
 
    Enum doc.
 
diff --git a/test/example-40-enum.rst b/test/example-40-enum.rst
index a1d42ca86b9e..4d57622ef2bf 100644
--- a/test/example-40-enum.rst
+++ b/test/example-40-enum.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: enum mode
+.. c:enum:: mode
 
    Frobnication modes for :c:func:`frob`.
 
diff --git a/test/example-50-struct.rst b/test/example-50-struct.rst
index 2eff861c9534..8af41478333a 100644
--- a/test/example-50-struct.rst
+++ b/test/example-50-struct.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: struct list
+.. c:struct:: list
 
    Linked list node.
 
diff --git a/test/struct.rst b/test/struct.rst
index 1a0fa608147b..3fc33bce0255 100644
--- a/test/struct.rst
+++ b/test/struct.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: struct sample_struct
+.. c:struct:: sample_struct
 
    This is a sample struct
 
diff --git a/test/typedef-enum.rst b/test/typedef-enum.rst
index 56c9c8d06c94..7ae374fbe41e 100644
--- a/test/typedef-enum.rst
+++ b/test/typedef-enum.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: enum named
+.. c:enum:: named
 
    named typedeffed enum
 
@@ -9,7 +9,7 @@
       named enumeration
 
 
-.. c:type:: unnamed_t
+.. c:enum:: unnamed_t
 
    unnamed typedeffed enum
 
diff --git a/test/typedef-struct.rst b/test/typedef-struct.rst
index bb46f1fe7725..4b3ae234d24f 100644
--- a/test/typedef-struct.rst
+++ b/test/typedef-struct.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: struct named
+.. c:struct:: named
 
    named typedeffed struct
 
@@ -9,7 +9,7 @@
       named member
 
 
-.. c:type:: typedef_struct
+.. c:struct:: typedef_struct
 
    unnamed typedeffed struct
 
diff --git a/test/union.rst b/test/union.rst
index a6cc7b546551..9b13cb944f79 100644
--- a/test/union.rst
+++ b/test/union.rst
@@ -1,5 +1,5 @@
 
-.. c:type:: union foo
+.. c:union:: foo
 
    Union documentation.
 
@@ -14,7 +14,7 @@
       int member 2.
 
 
-   .. c:type:: struct _baz
+   .. c:struct:: _baz
 
       struct member.
 
-- 
2.20.1


Other related posts: