From: Vladimír Vondruš <mosra@centrum.cz>
Date: Thu, 12 Apr 2018 14:35:21 +0000 (+0200)
Subject: doxygen: verify that \param etc. is extracted out of a list as well.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=e8e0f60e721f5cf582fa4885010648f620fdea53;p=blog.git

doxygen: verify that \param etc. is extracted out of a list as well.

Previously this was asserting because I didn't expect Doxygen to be so
shitty and put these *inside* of some random list without ending that
list first. This also uncovers a lot of other nasty Doxygen bugs, so I'm
just creating a very restricted repro case that doesn't trigger them.

I lost all hope with Doxygen. Kill it with fire and start over.
---

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 0d8b5cb1..39aec712 100755
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -492,6 +492,23 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
     # A CSS class to be added inline (not propagated outside of the paragraph)
     add_inline_css_class = None
 
+    # Also, to make things even funnier, parameter and return value description
+    # come from inside of some paragraph and can be nested also inside lists
+    # and whatnot. This bubbles them up. Unfortunately they can be scattered
+    # around, so also merging them together.
+    def merge_parsed_subsections(parsed):
+        if parsed.templates:
+            out.templates.update(parsed.templates)
+        if parsed.params:
+            out.params.update(parsed.params)
+        if 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
+        if parsed.return_values:
+            out.return_values += parsed.return_values
+
     i: ET.Element
     for index, i in enumerate(element):
         # State used later
@@ -709,20 +726,9 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                 out.parsed += parsed.parsed
                 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. Unfortunately they can be scattered around, so merge them.
-            if parsed.templates:
-                out.templates.update(parsed.templates)
-            if parsed.params:
-                out.params.update(parsed.params)
-            if 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
-            if parsed.return_values:
-                out.return_values += parsed.return_values
+            # Paragraphs can have nested parameter / return value / ...
+            # descriptions, merge them to current state
+            merge_parsed_subsections(parsed)
 
             # The same is (of course) with bubbling up the <mcss:class>
             # element. Reset the current value with the value coming from
@@ -755,9 +761,16 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
             tag = 'ul' if i.tag == 'itemizedlist' else 'ol'
             out.parsed += '<{}{}>'.format(tag,
                 ' class="{}"'.format(add_css_class) if add_css_class else '')
+
             for li in i:
                 assert li.tag == 'listitem'
-                out.parsed += '<li>{}</li>'.format(parse_desc(state, li))
+                parsed = parse_desc_internal(state, li)
+                out.parsed += '<li>{}</li>'.format(parsed.parsed)
+
+                # Lists can have nested parameter / return value / ...
+                # descriptions, bubble them up. THIS IS FUCKEN UNBELIEVABLE.
+                merge_parsed_subsections(parsed)
+
             out.parsed += '</{}>'.format(tag)
 
         elif i.tag == 'table':
diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h
index 401cd8d2..65537eba 100644
--- a/doxygen/test/compound_detailed/File.h
+++ b/doxygen/test/compound_detailed/File.h
@@ -149,6 +149,8 @@ That goes also for the return values.
 
 Yes?
 
+ - We also need to
+ - extract them out of a list
 @retval 1337    1337 h4xx0r?!
 @retval 42      The answer. To everything
 */
diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html
index ec53c234..cd95dd06 100644
--- a/doxygen/test/compound_detailed/namespaceFoo.html
+++ b/doxygen/test/compound_detailed/namespaceFoo.html
@@ -252,7 +252,7 @@
                 </tr>
               </tbody>
             </table>
-<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>
+<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><ul><li>We also need to</li><li>extract them out of a list</li></ul>
           </div></section>
           <section class="m-dox-details" id="a1e4e8c2c75da6e24d78c8a84e0cb3226"><div>
             <h3>