From: Vladimír Vondruš Date: Fri, 29 Mar 2019 12:25:02 +0000 (+0100) Subject: doxygen: avoid showing undocumented enum values twice. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=bf8dfed93d731ab0c188e06781a86886827c6f71;p=blog.git doxygen: avoid showing undocumented enum values twice. --- diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 0585fa9e..b4b8d9cb 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -1736,7 +1736,6 @@ def parse_enum(state: State, element: ET.Element): value.brief = parse_desc(state, enumvalue.find('briefdescription')) value.description, value_search_keywords, value.is_deprecated = parse_enum_value_desc(state, enumvalue) if value.brief or value.description: - enum.has_value_details = True if enum.base_url == state.current_compound_url and not state.doxyfile['M_SEARCH_DISABLED']: result = Empty() result.flags = ResultFlag.ENUM_VALUE|(ResultFlag.DEPRECATED if value.is_deprecated else ResultFlag(0)) @@ -1747,6 +1746,16 @@ def parse_enum(state: State, element: ET.Element): if search_enum_values_as_keywords and value.initializer.startswith('='): result.keywords += [(value.initializer[1:].lstrip(), '', 0)] state.search += [result] + + # If either brief or description for this value is present, we want + # to show the detailed enum docs. However, in + # case M_SHOW_UNDOCUMENTED is enabled, the values might have just + # a dummy content in order to make them "appear + # documented". Then it doesn't make sense to repeat the same list + # twice. + if not state.doxyfile['M_SHOW_UNDOCUMENTED'] or value.brief != '': + enum.has_value_details = True + enum.values += [value] if enum.base_url == state.current_compound_url and (enum.description or enum.has_value_details): diff --git a/doxygen/templates/details-enum.html b/doxygen/templates/details-enum.html index e95b5590..dabcbb12 100644 --- a/doxygen/templates/details-enum.html +++ b/doxygen/templates/details-enum.html @@ -23,7 +23,7 @@ {% if enum.description %} {{ enum.description }} {% endif %} - {% if enum.values %} + {% if enum.has_value_details %} diff --git a/doxygen/test/test_undocumented.py b/doxygen/test/test_undocumented.py index 01c6b4fe..74c0de4d 100644 --- a/doxygen/test/test_undocumented.py +++ b/doxygen/test/test_undocumented.py @@ -57,4 +57,4 @@ class Test(IntegrationTestCase): with open(os.path.join(self.path, 'html', 'searchdata.bin'), 'rb') as f: serialized = f.read() magic, version, symbol_count, map_offset = search_data_header_struct.unpack_from(serialized) - self.assertEqual(symbol_count, 38) + self.assertEqual(symbol_count, 44) diff --git a/doxygen/test/undocumented/Directory/File.h b/doxygen/test/undocumented/Directory/File.h index 71622df4..ce6f3812 100644 --- a/doxygen/test/undocumented/Directory/File.h +++ b/doxygen/test/undocumented/Directory/File.h @@ -12,7 +12,17 @@ struct Struct {}; union Union {}; /* An undocumented enum in the root namespace */ -enum Enum {}; +enum Enum { + A, + + /** + * This value is documented so the enum *should* be present in detailed + * docs. + */ + B, + + C +}; /* An undocumented typedef in the root namespace */ typedef int Int; @@ -51,7 +61,11 @@ struct ClassInANamespace { }; /* An undocumented enum */ -enum EnumInANamespace {}; +enum EnumInANamespace { + /* None of these are documented so the enum shouldn't be present in + detailed docs */ + A, B, C +}; /* An undocumented typedef */ typedef int IntInANamespace; diff --git a/doxygen/test/undocumented/File_8h.html b/doxygen/test/undocumented/File_8h.html index c189dc47..ea91b67f 100644 --- a/doxygen/test/undocumented/File_8h.html +++ b/doxygen/test/undocumented/File_8h.html @@ -111,11 +111,15 @@

Enums

- enum Enum { } + enum Enum { A, + B, + C }
- enum EnumInANamespace { } + enum EnumInANamespace { A, + B, + C }
@@ -221,6 +225,38 @@
+
+

Enum documentation

+
+

+ enum Enum +

+

+
Enumerators
+ + + + + + + + + + + + + + + +
Enumerators
A +

+
B +

This value is documented so the enum should be present in detailed docs.

+
C +

+
+ + diff --git a/doxygen/test/undocumented/namespaceNamespace.html b/doxygen/test/undocumented/namespaceNamespace.html index 7d9b828b..c7837502 100644 --- a/doxygen/test/undocumented/namespaceNamespace.html +++ b/doxygen/test/undocumented/namespaceNamespace.html @@ -86,7 +86,9 @@

Enums

- enum EnumInANamespace { } + enum EnumInANamespace { A, + B, + C }