From d44d4609099080f881a656d885232bc51bbf101c Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Fri, 14 Jan 2022 12:19:35 +0100 Subject: [PATCH] documentation/doxygen: don't trip up on WEIRD macros parsed as functions. --- documentation/doxygen.py | 6 +- .../cpp_mishandled_macro_call/Doxyfile | 15 ++++ .../cpp_mishandled_macro_call/File.h | 27 +++++++ .../cpp_mishandled_macro_call/File_8h.html | 71 +++++++++++++++++++ documentation/test_doxygen/test_cpp.py | 9 +++ 5 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 documentation/test_doxygen/cpp_mishandled_macro_call/Doxyfile create mode 100644 documentation/test_doxygen/cpp_mishandled_macro_call/File.h create mode 100644 documentation/test_doxygen/cpp_mishandled_macro_call/File_8h.html diff --git a/documentation/doxygen.py b/documentation/doxygen.py index afc8ccaa..d8da630b 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -2087,7 +2087,11 @@ def parse_func(state: State, element: ET.Element): name = p.find('declname') param = Empty() param.name = name.text if name is not None else '' - param.type = parse_type(state, p.find('type')) + param_type = p.find('type') + if param_type is None: + logging.warning("{}: parameter {} of function {} has no type, ignoring the whole function as it's suspected to be a mishandled macro call".format(state.current, param.name, func.name)) + return None + param.type = parse_type(state, param_type) # Recombine parameter name and array information back array = p.find('array') diff --git a/documentation/test_doxygen/cpp_mishandled_macro_call/Doxyfile b/documentation/test_doxygen/cpp_mishandled_macro_call/Doxyfile new file mode 100644 index 00000000..7e7e2ceb --- /dev/null +++ b/documentation/test_doxygen/cpp_mishandled_macro_call/Doxyfile @@ -0,0 +1,15 @@ +INPUT = File.h +AUTOLINK_SUPPORT = NO +QUIET = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +CASE_SENSE_NAMES = YES + +##! M_PAGE_FINE_PRINT = +##! M_THEME_COLOR = +##! M_FAVICON = +##! M_LINKS_NAVBAR1 = +##! M_LINKS_NAVBAR2 = +##! M_SEARCH_DISABLED = YES diff --git a/documentation/test_doxygen/cpp_mishandled_macro_call/File.h b/documentation/test_doxygen/cpp_mishandled_macro_call/File.h new file mode 100644 index 00000000..1700633c --- /dev/null +++ b/documentation/test_doxygen/cpp_mishandled_macro_call/File.h @@ -0,0 +1,27 @@ +/** @file + * @brief A file. + */ + +/** @brief A function-defining macro */ +#define DEFINE_FUNCTION(name) int function_ ## name(int param) + +/** +@brief A function-defining macro call + +This one is misparsed as a function definition and because it doesn't do +anything that would make it look suspicious, it will appear in the output. +*/ +DEFINE_FUNCTION(a) { + return param; +} + +/** +@brief A function-defining macro call + +In this case the $ will however lead to the parameter to have a declname but +not a type, which triggers a suspicion in the parser and so the whole function +gets ignored. +*/ +DEFINE_FUNCTION($) { + return param; +} diff --git a/documentation/test_doxygen/cpp_mishandled_macro_call/File_8h.html b/documentation/test_doxygen/cpp_mishandled_macro_call/File_8h.html new file mode 100644 index 00000000..3e27ba5c --- /dev/null +++ b/documentation/test_doxygen/cpp_mishandled_macro_call/File_8h.html @@ -0,0 +1,71 @@ + + + + + File.h file | My Project + + + + + +

+ File.h file +

A file.

+ +

Functions

+ DEFINE_FUNCTION(a) +: A function-defining macro call.

Defines

+ #define DEFINE_FUNCTION(name) +: A function-defining macro.

Function documentation

+ DEFINE_FUNCTION(a) +

A function-defining macro call.

This one is misparsed as a function definition and because it doesn't do anything that would make it look suspicious, it will appear in the output.

+ + diff --git a/documentation/test_doxygen/test_cpp.py b/documentation/test_doxygen/test_cpp.py index fed05c75..2802f539 100644 --- a/documentation/test_doxygen/test_cpp.py +++ b/documentation/test_doxygen/test_cpp.py @@ -97,3 +97,12 @@ class FunctionAttributesNospace(IntegrationTestCase): def test(self): self.run_doxygen(wildcard='structFoo.xml') self.assertEqual(*self.actual_expected_contents('structFoo.html')) + +class MishandledMacroCall(IntegrationTestCase): + def test(self): + with self.assertLogs() as cm: + self.run_doxygen(wildcard='*.xml') + self.assertEqual(*self.actual_expected_contents('File_8h.html')) + self.assertEqual(cm.output, [ + "WARNING:root:File_8h.xml: parameter $ of function DEFINE_FUNCTION has no type, ignoring the whole function as it's suspected to be a mishandled macro call" + ]) -- 2.30.2