From: Vladimír Vondruš Date: Fri, 9 Feb 2018 20:49:19 +0000 (+0100) Subject: doxygen: support the \retval command. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=5e6d0bcaae00412c3acbd371f11ef6276af6d0b9;p=blog.git doxygen: support the \retval command. --- diff --git a/doc/doxygen.rst b/doc/doxygen.rst index 5e833245..105a7502 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -1273,6 +1273,8 @@ Property Description details. :py:`func.has_param_details` If function parameters have description :py:`func.return_value` Return value description. Can be empty. +:py:`func.return_values` Description of particular empty values. See + below for details. :py:`func.brief` Brief description. Can be empty. [1]_ :py:`func.description` Detailed description. Can be empty. [2]_ :py:`func.has_details` If there is enough content for the full @@ -1325,6 +1327,12 @@ Property Description :py:`'inout'` or :py:`''` if unspecified. =========================== =================================================== +The :py:`func.return_values` is a list of return values and their description +(in contract to :py:`func.return_value`, which is just a single description). +Each item is a tuple of :py:`(value, description)`. Can be empty, it can also +happen that both :py:`func.return_value` and :py:`func.return_values` are +present. + `Variable properties`_ `````````````````````` diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 7aeb7f9d..6c9896b8 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -440,6 +440,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.templates = {} out.params = {} out.return_value = None + out.return_values = [] out.add_css_class = None out.footer_navigation = False out.example_navigation = None @@ -706,6 +707,8 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. logging.warning("{}: superfluous @return section found, ignoring: {} ".format(state.current, ''.join(i.itertext()))) else: out.return_value = parsed.return_value + if parsed.return_values: + out.return_values += parsed.return_values # The same is (of course) with bubbling up the # element. Reset the current value with the value coming from @@ -869,6 +872,8 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. for name in param_names.findall('parametername'): if i.attrib['kind'] == 'param': out.params[name.text] = (description, name.attrib['direction'] if 'direction' in name.attrib else '') + elif i.attrib['kind'] == 'retval': + out.return_values += [(name.text, description)] else: assert i.attrib['kind'] == 'templateparam' out.templates[name.text] = description @@ -1254,7 +1259,7 @@ def parse_func_desc(state: State, element: ET.Element): 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.search_keywords, parsed.is_deprecated) + return (parsed.parsed, parsed.templates, parsed.params, parsed.return_value, parsed.return_values, 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 @@ -1398,7 +1403,7 @@ def parse_func(state: State, element: ET.Element): func.type = parse_type(state, element.find('type')) func.name = fix_type_spacing(html.escape(element.find('name').text)) func.brief = parse_desc(state, element.find('briefdescription')) - func.description, templates, params, func.return_value, search_keywords, func.is_deprecated = parse_func_desc(state, element) + func.description, templates, params, func.return_value, func.return_values, search_keywords, func.is_deprecated = parse_func_desc(state, element) # Extract function signature to prefix, suffix and various flags. Important # things affecting caller such as static or const (and rvalue overloads) @@ -1481,7 +1486,7 @@ def parse_func(state: State, element: ET.Element): # Some param description got unused if params: logging.warning("{}: function parameter description doesn't match parameter names: {}".format(state.current, repr(params))) - func.has_details = func.description or func.has_template_details or func.has_param_details or func.return_value + func.has_details = func.description or func.has_template_details or func.has_param_details or func.return_value or func.return_values if func.brief or func.has_details: if not state.doxyfile['M_SEARCH_DISABLED']: result = Empty() diff --git a/doxygen/templates/details-func.html b/doxygen/templates/details-func.html index 5543fc1c..0b38eefc 100644 --- a/doxygen/templates/details-func.html +++ b/doxygen/templates/details-func.html @@ -18,7 +18,7 @@ {% if func.brief %}

{{ func.brief }}

{% endif %} - {% if func.has_template_details or func.has_param_details or func.return_value %} + {% if func.has_template_details or func.has_param_details or func.return_value or func.return_values %} {% if func.has_template_details %} @@ -47,12 +47,26 @@ {% endif %} {% if func.return_value %} - + {{ '' if func.return_values else '' }} Returns - + {{ '' if func.return_values else '' }} + {% elif func.return_values %} + + + + {% endif %} + {% if func.return_values %} + + {% for value, description in func.return_values %} + + {{ value }} + + + {% endfor %} + {% endif %}
{{ func.return_value }}
Returns
{{ description }}
{% endif %} diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h index 92fe3e19..3d6329c6 100644 --- a/doxygen/test/compound_detailed/File.h +++ b/doxygen/test/compound_detailed/File.h @@ -101,6 +101,8 @@ namespace Foo { @param things And an array! @param stuff Another array @return It returns! +@retval 0 Zero? +@retval 42 The Answer. Ooooh, more text! */ @@ -120,6 +122,12 @@ constexpr void bar(int in, int& out, void* shit) noexcept; */ int justReturn(); +/** +@brief Function +@retval 42 With just return value docs should still have detailed section +*/ +int justReturnValues(); + /** @brief A function with scattered docs @@ -133,8 +141,17 @@ merged and reordered. @tparam A First template parameter docs @param b Second parameter docs + +That goes also for the return values. + +@retval 0 Zero + +Yes? + +@retval 1337 1337 h4xx0r?! +@retval 42 The answer. To everything */ -template void bar(int a, int b); +template int bar(int a, int b); /** @brief Function with one description for all params diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html index 9cca2f28..918fdfc2 100644 --- a/doxygen/test/compound_detailed/namespaceFoo.html +++ b/doxygen/test/compound_detailed/namespaceFoo.html @@ -55,10 +55,14 @@ auto justReturn() -> int
Function.
+
+ auto justReturnValues() -> int +
+
Function.
template<class A, class B>
- void bar(int a, - int b) + auto bar(int a, + int b) -> int
A function with scattered docs.
@@ -116,12 +120,22 @@ Another array - + Returns It returns! - + + + + 0 + Zero? + + + 42 + The Answer. + +

Ooooh, more text!

@@ -166,12 +180,29 @@ -
+
+

+ int Foo::justReturnValues() +

+

Function.

+ + + + + + + + + + +
Returns
42With just return value docs should still have detailed section
+
+

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

A function with scattered docs.

@@ -202,8 +233,25 @@ Second parameter docs + + Returns + + + + 0 + Zero + + + 1337 + 1337 h4xx0r?! + + + 42 + The answer. To everything + + -

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

+

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

That goes also for the return values.

Yes?