doxygen: support the \retval command.

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index 5e833245bf1a5c95783328124252e3544376a14a..105a7502e3202a658cdc8b3af5c6d5b03a7873a9 100644 (file)
--- 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 7aeb7f9db524341a4c0e04fc73084be9c1acf458..6c9896b80941063c99bdf9b84dc20e8ed7a3cc89 100755 (executable)
--- 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 <mcss:class>
             # 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 5543fc1cdf9e01b8349a119472b4be5d06f0e5e2..0b38eefc2b2e54600fd28932bed6ecc577d82c7b 100644 (file)
--- a/doxygen/templates/details-func.html
+++ b/doxygen/templates/details-func.html
@@ -18,7 +18,7 @@
             {% if func.brief %}
             <p>{{ func.brief }}</p>
             {% 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 %}
             <table class="m-table m-fullwidth m-flat">
               {% if func.has_template_details %}
               <thead>
@@ -47,12 +47,26 @@
               </tbody>
               {% endif %}
               {% if func.return_value %}
-              <tfoot>
+              {{ '<thead>' if func.return_values else '<tfoot>' }}
                 <tr>
                   <th{% if not func.has_template_details and not func.has_param_details %} style="width: 1%"{% endif %}>Returns</th>
                   <td>{{ func.return_value }}</td>
                 </tr>
-              </tfoot>
+              {{ '</thead>' if func.return_values else '</tfoot>' }}
+              {% elif func.return_values %}
+              <thead>
+                <tr><th colspan="2">Returns</th></tr>
+              </thead>
+              {% endif %}
+              {% if func.return_values %}
+              <tbody>
+                {% for value, description in func.return_values %}
+                <tr>
+                  <td{% if loop.index == 1 and not func.has_template_details and not func.has_param_details and not func.return_value %} style="width: 1%"{% endif %}>{{ value }}</td>
+                  <td>{{ description }}</td>
+                </tr>
+                {% endfor %}
+              </tbody>
               {% endif %}
             </table>
             {% endif %}

diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h
index 92fe3e19543b0ec711efdda1ff002634ff106c44..3d6329c662c1d54f776fa1425796c374139bf10f 100644 (file)
--- 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<class A, class B> void bar(int a, int b);
+template<class A, class B> 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 9cca2f28520010fa3fac063acbd029efbcbc15b9..918fdfc2017d16fec4b1f4c84b28929e0a58597c 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceFoo.html
+++ b/doxygen/test/compound_detailed/namespaceFoo.html
@@ -55,10 +55,14 @@
               <span class="m-dox-wrap-bumper">auto <a href="#ada6488b07291f349307778cc7bb3547d" class="m-dox">justReturn</a>(</span><span class="m-dox-wrap">) -&gt; int</span>
             </dt>
             <dd>Function.</dd>
+            <dt>
+              <span class="m-dox-wrap-bumper">auto <a href="#a2aed7a8280e0ed79f5f9ceb0d54f4a30" class="m-dox">justReturnValues</a>(</span><span class="m-dox-wrap">) -&gt; int</span>
+            </dt>
+            <dd>Function.</dd>
             <dt>
               <div class="m-dox-template">template&lt;class A, class B&gt;</div>
-              <span class="m-dox-wrap-bumper">void <a href="#a291ca0ca1dec918416a1316b23de0e42" class="m-dox">bar</a>(</span><span class="m-dox-wrap">int a,
-              int b)</span>
+              <span class="m-dox-wrap-bumper">auto <a href="#aea7a925ccf30c967a965b2549cec4154" class="m-dox">bar</a>(</span><span class="m-dox-wrap">int a,
+              int b) -&gt; int</span>
             </dt>
             <dd>A function with scattered docs.</dd>
             <dt>
@@ -116,12 +120,22 @@
                   <td>Another array</td>
                 </tr>
               </tbody>
-              <tfoot>
+              <thead>
                 <tr>
                   <th>Returns</th>
                   <td>It returns!</td>
                 </tr>
-              </tfoot>
+              </thead>
+              <tbody>
+                <tr>
+                  <td>0</td>
+                  <td>Zero?</td>
+                </tr>
+                <tr>
+                  <td>42</td>
+                  <td>The Answer.</td>
+                </tr>
+              </tbody>
             </table>
 <p>Ooooh, more text!</p>
           </div></section>
@@ -166,12 +180,29 @@
               </tfoot>
             </table>
           </div></section>
-          <section class="m-dox-details" id="a291ca0ca1dec918416a1316b23de0e42"><div>
+          <section class="m-dox-details" id="a2aed7a8280e0ed79f5f9ceb0d54f4a30"><div>
+            <h3>
+              <span class="m-dox-wrap-bumper">int Foo::<wbr /></span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#a2aed7a8280e0ed79f5f9ceb0d54f4a30" class="m-dox-self">justReturnValues</a>(</span><span class="m-dox-wrap">)</span></span>
+            </h3>
+            <p>Function.</p>
+            <table class="m-table m-fullwidth m-flat">
+              <thead>
+                <tr><th colspan="2">Returns</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td style="width: 1%">42</td>
+                  <td>With just return value docs should still have detailed section</td>
+                </tr>
+              </tbody>
+            </table>
+          </div></section>
+          <section class="m-dox-details" id="aea7a925ccf30c967a965b2549cec4154"><div>
             <h3>
               <div class="m-dox-template">
                 template&lt;class A, class B&gt;
               </div>
-              <span class="m-dox-wrap-bumper">void Foo::<wbr /></span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#a291ca0ca1dec918416a1316b23de0e42" class="m-dox-self">bar</a>(</span><span class="m-dox-wrap">int a,
+              <span class="m-dox-wrap-bumper">int Foo::<wbr /></span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#aea7a925ccf30c967a965b2549cec4154" class="m-dox-self">bar</a>(</span><span class="m-dox-wrap">int a,
               int b)</span></span>
             </h3>
             <p>A function with scattered docs.</p>
@@ -202,8 +233,25 @@
                   <td>Second parameter docs</td>
                 </tr>
               </tbody>
+              <thead>
+                <tr><th colspan="2">Returns</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td>0</td>
+                  <td>Zero</td>
+                </tr>
+                <tr>
+                  <td>1337</td>
+                  <td>1337 h4xx0r?!</td>
+                </tr>
+                <tr>
+                  <td>42</td>
+                  <td>The answer. To everything</td>
+                </tr>
+              </tbody>
             </table>
-<p>This is a function that has the docs all scattered around. They should get merged and reordered.</p>
+<p>This is a function that has the docs all scattered around. They should get merged and reordered.</p><p>That goes also for the return values.</p><p>Yes?</p>
           </div></section>
           <section class="m-dox-details" id="a1e4e8c2c75da6e24d78c8a84e0cb3226"><div>
             <h3>