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 a921cc4ffa441d806ad5c202850fe3d8c8c3f71f..5407fbd1c0374ad7bcfd42faef702fc300cda495 100755 (executable)
--- 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 += '</p>'
 
             # 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 <mcss:class>
             # 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 a3bea6da004da409e0c8873d72fb83be1dac7c1a..655125b32848236b2be5d68462bb17ae9aee730f 100644 (file)
--- 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<class A, class B> 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 29f2ba6e22cafc9fc91bdc4ab8fb658478619bd5..0b58c1ae0b7866521f8e347049fd9df1c699ec62 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceFoo.html
+++ b/doxygen/test/compound_detailed/namespaceFoo.html
@@ -53,6 +53,12 @@
               <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>
+              <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>
+            </dt>
+            <dd>A function with scattered docs.</dd>
           </dl>
         </section>
         <section>
@@ -146,6 +152,45 @@
               </tfoot>
             </table>
           </div></section>
+          <section class="m-dox-details" id="a291ca0ca1dec918416a1316b23de0e42"><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,
+              int b)</span></span>
+            </h3>
+            <p>A function with scattered docs.</p>
+            <table class="m-table m-fullwidth m-flat">
+              <thead>
+                <tr><th colspan="2">Template parameters</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td style="width: 1%">A</td>
+                  <td>First template parameter docs</td>
+                </tr>
+                <tr>
+                  <td>B</td>
+                  <td>Second template parameter docs</td>
+                </tr>
+              </tbody>
+              <thead>
+                <tr><th colspan="2">Parameters</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td>a</td>
+                  <td>First parameter docs</td>
+                </tr>
+                <tr>
+                  <td>b</td>
+                  <td>Second parameter docs</td>
+                </tr>
+              </tbody>
+            </table>
+<p>This is a function that has the docs all scattered around. They should get merged and reordered.</p>
+          </div></section>
         </section>
       </div>
     </div>

diff --git a/doxygen/test/compound_detailed/namespaceWarning.html b/doxygen/test/compound_detailed/namespaceWarning.html
index 86b18d5f09d624e0aa80251adc88a807ccbfc794..d37b6283fab7bc226249d57345155e3628c70337 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceWarning.html
+++ b/doxygen/test/compound_detailed/namespaceWarning.html
@@ -65,6 +65,7 @@
                 </tr>
               </tfoot>
             </table>
+<p>Function details.</p>
           </div></section>
         </section>
       </div>