[gtk-doc: 2/5] Support type/enum deprecation decorators

[Xavier Claessens <xclaesse src gnome org>]

commit 7aa34874b86e52984770703293e9c7ac40519559
Author: Xavier Claessens <xavier claessens collabora com>
Date:   Tue Jul 9 08:21:22 2019 -0400

    Support type/enum deprecation decorators
    
    GLib recently introduced new kind of deprecation macros, to annotate
    types and enum values.
    
    For example: `typedef _MyType MyType DEPRECATED_FOR(MyOtherType);`

 gtkdoc/scan.py                      | 41 ++++++++++++++++++++++++--------
 tests/bugs/docs/Makefile.am         |  2 +-
 tests/bugs/docs/meson.build         |  2 +-
 tests/bugs/docs/tester-sections.txt |  5 ++++
 tests/bugs/src/tester.h             | 47 +++++++++++++++++++++++++++++++++++++
 5 files changed, 85 insertions(+), 12 deletions(-)
---
diff --git a/gtkdoc/scan.py b/gtkdoc/scan.py
index 804a7b3..4ffe5fe 100644
--- a/gtkdoc/scan.py
+++ b/gtkdoc/scan.py
@@ -81,14 +81,10 @@ CLINE_MATCHER = [
         r"""^\s*enum\s+
         _?(\w+)                              # 1: name
         \s+\{""", re.VERBOSE),
-    re.compile(r'^\s*typedef\s+enum\s+_?(\w+)\s+\1\s*;'),
+    None,  # in ScanHeaderContent()
     re.compile(r'^\s*typedef\s+enum'),
     # 8-11: STRUCTS AND UNIONS
-    re.compile(
-        r"""^\s*typedef\s+
-        (struct|union)\s+                    # 1: struct/union
-        _(\w+)                               # 2: name
-        \s+\2\s*;""", re.VERBOSE),
+    None,  # in ScanHeaderContent()
     re.compile(r'^\s*(?:struct|union)\s+_(\w+)\s*;'),
     re.compile(
         r"""^\s*
@@ -377,8 +373,10 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
 
     # avoid generating regex with |'' (matching no string)
     ignore_decorators = ''
+    optional_decorators_regex = ''
     if options.ignore_decorators:
         ignore_decorators = '|' + options.ignore_decorators.replace('()', '\(\w*\)')
+        optional_decorators_regex = '(?:\s+(?:%s))?' % ignore_decorators[1:]
 
     # FUNCTION POINTER VARIABLES
     CLINE_MATCHER[4] = re.compile(
@@ -389,6 +387,14 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
         \(\*\s*
           (\w+)                                        # 4: name
         \)\s*\(""" % ignore_decorators, re.VERBOSE)
+
+    CLINE_MATCHER[6] = re.compile(r'^\s*typedef\s+enum\s+_?(\w+)\s+\1%s\s*;' % optional_decorators_regex)
+    CLINE_MATCHER[8] = re.compile(
+        r"""^\s*typedef\s+
+        (struct|union)\s+                    # 1: struct/union
+        _(\w+)\s+\2                          # 2: name
+        %s                                   # 3: optional decorator
+        \s*;""" % optional_decorators_regex, re.VERBOSE)
     # OTHER TYPEDEFS
     CLINE_MATCHER[15] = re.compile(
         r"""^\s*
@@ -882,19 +888,33 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
                 in_declaration = ''
 
         if in_declaration == 'enum':
-            em = re.search(r'\}\s*(\w+)?;\s*$', decl)
+            # Examples:
+            # "};"
+            # "} MyEnum;"
+            # "} MyEnum DEPRECATED_FOR(NewEnum);"
+            # "} DEPRECATED_FOR(NewEnum);"
+            em = re.search(r'\n\s*\}\s*(?:(\w+)?%s)?;\s*$' % optional_decorators_regex, decl)
             if em:
                 if symbol == '':
                     symbol = em.group(1)
+                # Enums could contain deprecated values and that doesn't mean
+                # the whole enum is deprecated, so they are ignored when setting
+                # deprecated_conditional_nest above. Here we can check if the
+                # _DEPRECATED is between '}' and ';' which would mean the enum
+                # as a whole is deprecated.
+                if re.search(r'\n\s*\}.*_DEPRECATED.*;\s*$', decl):
+                    deprecated = '<DEPRECATED/>\n'
                 if AddSymbolToList(slist, symbol):
-                    decl_list.append('<ENUM>\n<NAME>%s</NAME>\n%s%s</ENUM>\n' % (symbol, deprecated, decl))
+                    stripped_decl = re.sub(optional_decorators_regex, '', decl)
+                    decl_list.append('<ENUM>\n<NAME>%s</NAME>\n%s%s</ENUM>\n' % (symbol, deprecated, 
stripped_decl))
                 deprecated_conditional_nest = int(deprecated_conditional_nest)
                 in_declaration = ''
 
         # We try to handle nested structs/unions, but unmatched brackets in
         # comments will cause problems.
         if in_declaration == 'struct' or in_declaration == 'union':
-            sm = re.search(r'\n\}\s*(\w*);\s*$', decl)
+            # Same regex as for enum
+            sm = re.search(r'\n\}\s*(?:(\w+)?%s)?;\s*$' % optional_decorators_regex, decl)
             if level <= 1 and sm:
                 if symbol == '':
                     symbol = sm.group(1)
@@ -908,8 +928,9 @@ def ScanHeaderContent(input_lines, decl_list, get_types, options):
                 logging.info('Store struct: "%s"', symbol)
                 if AddSymbolToList(slist, symbol):
                     structsym = in_declaration.upper()
+                    stripped_decl = re.sub('(%s)' % optional_decorators_regex, '', decl)
                     decl_list.append('<%s>\n<NAME>%s</NAME>\n%s%s</%s>\n' %
-                                     (structsym, symbol, deprecated, decl, structsym))
+                                     (structsym, symbol, deprecated, stripped_decl, structsym))
                     if symbol in forward_decls:
                         del forward_decls[symbol]
                 deprecated_conditional_nest = int(deprecated_conditional_nest)
diff --git a/tests/bugs/docs/Makefile.am b/tests/bugs/docs/Makefile.am
index d09c94a..2f33b00 100644
--- a/tests/bugs/docs/Makefile.am
+++ b/tests/bugs/docs/Makefile.am
@@ -19,7 +19,7 @@ SCANGOBJ_OPTIONS=
 
 # Extra options to supply to gtkdoc-scan.
 SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \
-  --ignore-decorators='GLIB_VAR|GTKDOC_GNUC_CONST|BUG_711598_DEPRECATED_FOR()' \
+  --ignore-decorators='GLIB_VAR|GTKDOC_GNUC_CONST|BUG_711598_DEPRECATED_FOR()|MY_DEPRECATED_FOR()' \
   --rebuild-types
 
 # Extra options to supply to gtkdoc-mkdb.
diff --git a/tests/bugs/docs/meson.build b/tests/bugs/docs/meson.build
index e39d446..726cf4d 100644
--- a/tests/bugs/docs/meson.build
+++ b/tests/bugs/docs/meson.build
@@ -34,7 +34,7 @@ test(
     '--source-dir=@0@'.format(bugs_test_source_dir),
     '--ignore-headers=config.h',
     '--deprecated-guards=GTKDOC_TESTER_DISABLE_DEPRECATED',
-    '--ignore-decorators=GLIB_VAR|GTKDOC_GNUC_CONST|BUG_711598_DEPRECATED_FOR()',
+    '--ignore-decorators=GLIB_VAR|GTKDOC_GNUC_CONST|BUG_711598_DEPRECATED_FOR()|MY_DEPRECATED_FOR()',
     '--rebuild-types',
   ],
 )
diff --git a/tests/bugs/docs/tester-sections.txt b/tests/bugs/docs/tester-sections.txt
index 9e6a5ff..4329e37 100644
--- a/tests/bugs/docs/tester-sections.txt
+++ b/tests/bugs/docs/tester-sections.txt
@@ -12,6 +12,10 @@ Bug512154
 Bug644291
 Bug000000Scope
 Bug76
+MyDeprecatedEnum
+MyNotDeprecatedEnum
+MyDeprecatedStruct
+MyNotDeprecatedStruct
 <SUBSECTION Functions>
 bug_000000_va1
 BUG_000000_VA2
@@ -68,4 +72,5 @@ GLIB_DEPRECATED
 BUG_711598_DEPRECATED_FOR
 bug_554833_new
 G_GNUC_NONNULL
+MY_DEPRECATED_FOR
 </SECTION>
diff --git a/tests/bugs/src/tester.h b/tests/bugs/src/tester.h
index 0940e3e..6e05de8 100644
--- a/tests/bugs/src/tester.h
+++ b/tests/bugs/src/tester.h
@@ -432,4 +432,51 @@ struct _Bug76
 };
 typedef struct _Bug76   Bug76;
 
+#define MY_DEPRECATED_FOR(val)
+
+/**
+ * MyNotDeprecatedEnum:
+ * @MY_NOT_DEPRECATED_ENUM_VAL1: new value
+ *
+ * some description
+ */
+typedef enum {
+  MY_NOT_DEPRECATED_ENUM_VAL1,
+} MyNotDeprecatedEnum;
+
+/**
+ * MyDeprecatedEnum:
+ * @MY_DEPRECATED_ENUM_VAL1: deprecated, use instead %MY_DEPRECATED_ENUM_VAL2
+ * @MY_DEPRECATED_ENUM_VAL2: val2
+ *
+ * some description
+ * Deprecated: Use #MyNotDeprecatedEnum instead
+ */
+typedef enum {
+  MY_DEPRECATED_ENUM_VAL1 MY_DEPRECATED_FOR(MY_DEPRECATED_ENUM_VAL2),
+  MY_DEPRECATED_ENUM_VAL2,
+} MyDeprecatedEnum MY_DEPRECATED_FOR(MyNotDeprecatedEnum);
+
+/**
+ * MyDeprecatedStruct:
+ *
+ * some description
+ * Deprecated: Use #MyNotDeprecatedStruct instead
+ */
+typedef struct _MyDeprecatedStruct  MyDeprecatedStruct MY_DEPRECATED_FOR(MyNotDeprecatedStruct);
+struct _MyDeprecatedStruct {
+  /*< private >*/
+  guint index;
+} MY_DEPRECATED_FOR(MyNotDeprecatedStruct);
+
+/**
+ * MyNotDeprecatedStruct:
+ *
+ * some description
+ */
+typedef struct {
+  /*< private >*/
+  guint index_plop;
+} MyNotDeprecatedStruct;
+
 #endif // GTKDOC_TESTER_H