diff options
author | Xavier Claessens <xavier.claessens@collabora.com> | 2019-07-09 08:21:22 -0400 |
---|---|---|
committer | Xavier Claessens <xavier.claessens@collabora.com> | 2019-07-17 11:51:15 -0400 |
commit | 7aa34874b86e52984770703293e9c7ac40519559 (patch) | |
tree | 7746a02837d2bbf65644957fc4ee44a42616c22e | |
parent | 803f9982c3258fc4dcda7616e910dc2873d92d9e (diff) | |
download | gtk-doc-7aa34874b86e52984770703293e9c7ac40519559.tar.gz |
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);`
-rw-r--r-- | gtkdoc/scan.py | 41 | ||||
-rw-r--r-- | tests/bugs/docs/Makefile.am | 2 | ||||
-rw-r--r-- | tests/bugs/docs/meson.build | 2 | ||||
-rw-r--r-- | tests/bugs/docs/tester-sections.txt | 5 | ||||
-rw-r--r-- | 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 |