From: Vladimír Vondruš Date: Thu, 13 Sep 2018 12:47:41 +0000 (+0200) Subject: doxygen: don't assert on unexpected sections / commands. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=394339ea6ed6bcf4158b1f82d5bc5537880bf093;p=blog.git doxygen: don't assert on unexpected sections / commands. Until now, putting a @param into a variable description (or similar unexpected things) resulted in an assertion. Turns out this happens quite often, so I made that into a warning instead. The contents are simply ignored. --- diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index d79b8e36..4e092e8d 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -1387,25 +1387,25 @@ def parse_desc_keywords(state: State, element: ET.Element) -> str: return parsed.parsed, parsed.search_keywords, parsed.search_enum_values_as_keywords def parse_enum_desc(state: State, element: ET.Element) -> str: - # Verify that we didn't ignore any important info by accident parsed = parse_desc_internal(state, element.find('detaileddescription')) parsed.parsed += parse_desc(state, element.find('inbodydescription')) - assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions + if parsed.templates or parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions: + logging.warning("{}: unexpected @tparam / @param / @return / @retval / @exception found in enum description, ignoring".format(state.current)) assert not parsed.section # might be problematic return (parsed.parsed, parsed.search_keywords, parsed.search_enum_values_as_keywords, parsed.is_deprecated) def parse_enum_value_desc(state: State, element: ET.Element) -> str: - # Verify that we didn't ignore any important info by accident parsed = parse_desc_internal(state, element.find('detaileddescription')) - assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions + if parsed.templates or parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions: + logging.warning("{}: unexpected @tparam / @param / @return / @retval / @exception found in enum value description, ignoring".format(state.current)) assert not parsed.section # might be problematic return (parsed.parsed, parsed.search_keywords, parsed.is_deprecated) def parse_var_desc(state: State, element: ET.Element) -> str: - # Verify that we didn't ignore any important info by accident parsed = parse_desc_internal(state, element.find('detaileddescription')) parsed.parsed += parse_desc(state, element.find('inbodydescription')) - assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions + if parsed.templates or parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions: + logging.warning("{}: unexpected @tparam / @param / @return / @retval / @exception found in variable description, ignoring".format(state.current)) assert not parsed.section # might be problematic return (parsed.parsed, parsed.search_keywords, parsed.is_deprecated) @@ -1413,33 +1413,29 @@ def parse_toplevel_desc(state: State, element: ET.Element): state.parsing_toplevel_desc = True parsed = parse_desc_internal(state, element) state.parsing_toplevel_desc = False - # Verify that we didn't ignore any important info by accident - assert not parsed.return_value and not parsed.return_values and not parsed.exceptions - if parsed.params: - logging.warning("{}: use @tparam instead of @param for documenting class templates, @param is ignored".format(state.current)) + if parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions: + logging.warning("{}: unexpected @param / @return / @retval / @exception found in top-level description, ignoring".format(state.current)) return (parsed.parsed, parsed.templates, parsed.section[2] if parsed.section else '', parsed.footer_navigation, parsed.example_navigation, parsed.search_keywords, parsed.is_deprecated) def parse_typedef_desc(state: State, element: ET.Element): - # Verify that we didn't ignore any important info by accident parsed = parse_desc_internal(state, element.find('detaileddescription')) parsed.parsed += parse_desc(state, element.find('inbodydescription')) - assert not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions + if parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions: + logging.warning("{}: unexpected @param / @return / @retval / @exception found in typedef description, ignoring".format(state.current)) assert not parsed.section # might be problematic return (parsed.parsed, parsed.templates, parsed.search_keywords, parsed.is_deprecated) def parse_func_desc(state: State, element: ET.Element): - # Verify that we didn't ignore any important info by accident parsed = parse_desc_internal(state, element.find('detaileddescription')) parsed.parsed += parse_desc(state, element.find('inbodydescription')) assert not parsed.section # might be problematic return (parsed.parsed, parsed.templates, parsed.params, parsed.return_value, parsed.return_values, parsed.exceptions, parsed.search_keywords, parsed.is_deprecated) def parse_define_desc(state: State, element: ET.Element): - # Verify that we didn't ignore any important info by accident parsed = parse_desc_internal(state, element.find('detaileddescription')) parsed.parsed += parse_desc(state, element.find('inbodydescription')) - assert not parsed.templates and not parsed.exceptions - assert not parsed.return_values # might be problematic? + if parsed.templates or parsed.return_values or parsed.exceptions: + logging.warning("{}: unexpected @tparam / @retval / @exception found in macro description, ignoring".format(state.current)) assert not parsed.section # might be problematic return (parsed.parsed, parsed.params, parsed.return_value, parsed.search_keywords, parsed.is_deprecated) diff --git a/doxygen/test/contents_unexpected_sections/Doxyfile b/doxygen/test/contents_unexpected_sections/Doxyfile new file mode 100644 index 00000000..49e476ec --- /dev/null +++ b/doxygen/test/contents_unexpected_sections/Doxyfile @@ -0,0 +1,13 @@ +INPUT = File.h +QUIET = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO + +##! M_PAGE_FINE_PRINT = +##! M_THEME_COLOR = +##! M_FAVICON = +##! M_LINKS_NAVBAR1 = +##! M_LINKS_NAVBAR2 = +##! M_SEARCH_DISABLED = YES diff --git a/doxygen/test/contents_unexpected_sections/File.h b/doxygen/test/contents_unexpected_sections/File.h new file mode 100644 index 00000000..c941b654 --- /dev/null +++ b/doxygen/test/contents_unexpected_sections/File.h @@ -0,0 +1,34 @@ +/** @file +@brief A file + +@return Files don't return anyhting. +*/ + +/** +@brief An enum +@param what No, enums don't have params. +*/ +enum Foo { + /** + * @return Neither this. + */ + Value = 32 +}; + +/** +@brief A variable +@exception no Variables don't throw exceptions. +*/ +int variable; + +/** +@brief A typedef +@return Typedefs don't have return values. +*/ +typedef Foo Bar; + +/** +@brief A define +@tparam T Defines don't have templates. +*/ +#define FOOBAR 3 diff --git a/doxygen/test/contents_unexpected_sections/File_8h.html b/doxygen/test/contents_unexpected_sections/File_8h.html new file mode 100644 index 00000000..4c216465 --- /dev/null +++ b/doxygen/test/contents_unexpected_sections/File_8h.html @@ -0,0 +1,79 @@ + + + + + File.h file | My Project + + + + + +
+
+ + diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py index 721db559..6b93c0b2 100644 --- a/doxygen/test/test_contents.py +++ b/doxygen/test/test_contents.py @@ -320,3 +320,11 @@ class AnchorInBothGroupAndNamespace(IntegrationTestCase): def test(self): self.run_dox2html5(wildcard='namespaceFoo.xml') self.assertEqual(*self.actual_expected_contents('namespaceFoo.html')) + +class UnexpectedSections(IntegrationTestCase): + def __init__(self, *args, **kwargs): + super().__init__(__file__, 'unexpected_sections', *args, **kwargs) + + def test(self): + self.run_dox2html5(wildcard='File_8h.xml') + self.assertEqual(*self.actual_expected_contents('File_8h.html'))