From: Vladimír Vondruš Date: Mon, 29 Jan 2018 20:03:39 +0000 (+0100) Subject: doxygen: be less strict when parsing \param and \return. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=2ca745246df6b557f22f32ac767c3bbb9168c284;p=blog.git doxygen: be less strict when parsing \param and \return. They can be scattered around the documentation block, in different paragraphs. Combine them together and reorder as they should be. --- diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index a921cc4f..5407fbd1 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -400,17 +400,17 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. if parsed.write_paragraph_close_tag: out.parsed += '

' # Also, to make things even funnier, parameter and return value - # description come from inside of some paragraph, so bubble them up - # and assume they are not scattered all over the place (ugh). + # description come from inside of some paragraph, so bubble them + # up. Unfortunately they can be scattered around, so merge them. if parsed.templates: - assert not out.templates - out.templates = parsed.templates + out.templates.update(parsed.templates) if parsed.params: - assert not out.params - out.params = parsed.params + out.params.update(parsed.params) if parsed.return_value: - assert not out.return_value - out.return_value = parsed.return_value + if out.return_value: + logging.warning("{}: superfluous @return section found, ignoring: {} ".format(state.current, ''.join(i.itertext()))) + else: + out.return_value = parsed.return_value # The same is (of course) with bubbling up the # element. Reset the current value with the value coming from @@ -477,7 +477,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # Return value is separated from the text flow if i.attrib['kind'] == 'return': if out.return_value: - logging.warning("{}: superfluous @return section found, ignoring: {} ".format(state.current, parse_desc(state, i))) + logging.warning("{}: superfluous @return section found, ignoring: {} ".format(state.current, ''.join(i.itertext()))) else: out.return_value = parse_desc(state, i) # Ignore the RCS strings for now diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h index a3bea6da..655125b3 100644 --- a/doxygen/test/compound_detailed/File.h +++ b/doxygen/test/compound_detailed/File.h @@ -119,6 +119,22 @@ constexpr void bar(int in, int& out, void* shit) noexcept; */ int justReturn(); +/** +@brief A function with scattered docs + +@param a First parameter docs + +@tparam B Second template parameter docs + +This is a function that has the docs all scattered around. They should get +merged and reordered. + +@tparam A First template parameter docs + +@param b Second parameter docs +*/ +template void bar(int a, int b); + } namespace Eno { @@ -179,6 +195,10 @@ enum Enum { @param wrong This parameter is not here @return Returns nothing. @return Returns nothing, but second time. This is ignored. + +Function details. + +@return Returns nothing, third time, in a different paragraph. Ignored as well. */ void bar(); diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html index 29f2ba6e..0b58c1ae 100644 --- a/doxygen/test/compound_detailed/namespaceFoo.html +++ b/doxygen/test/compound_detailed/namespaceFoo.html @@ -53,6 +53,12 @@ auto justReturn() -> int
Function.
+
+
template<class A, class B>
+ void bar(int a, + int b) +
+
A function with scattered docs.
@@ -146,6 +152,45 @@
+
+

+
+ template<class A, class B> +
+ void Foo::bar(int a, + int b) +

+

A function with scattered docs.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + +
Template parameters
AFirst template parameter docs
BSecond template parameter docs
Parameters
aFirst parameter docs
bSecond parameter docs
+

This is a function that has the docs all scattered around. They should get merged and reordered.

+
diff --git a/doxygen/test/compound_detailed/namespaceWarning.html b/doxygen/test/compound_detailed/namespaceWarning.html index 86b18d5f..d37b6283 100644 --- a/doxygen/test/compound_detailed/namespaceWarning.html +++ b/doxygen/test/compound_detailed/namespaceWarning.html @@ -65,6 +65,7 @@ +

Function details.