From 778bf37ea04d8a51a5809c9fa54367c696862116 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 29 Jan 2018 21:56:25 +0100
Subject: [PATCH] doxygen: support `\param x, y, z Description`.

Oh, so that explains the massive complexity of the XML output. Ugh.
---
 doxygen/dox2html5.py                          | 22 ++++++++-----
 doxygen/test/compound_detailed/File.h         |  6 ++++
 .../test/compound_detailed/namespaceFoo.html  | 33 +++++++++++++++++++
 3 files changed, 53 insertions(+), 8 deletions(-)

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 8f08e571..c32f860d 100755
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -543,18 +543,24 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
             assert out.param_kind in ['param', 'templateparam']
             for param in i:
                 # This is an overcomplicated shit, so check sanity
+                # http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdparam
                 assert param.tag == 'parameteritem'
                 assert len(param.findall('parameternamelist')) == 1
-                assert param.find('parameternamelist').find('parametertype') is None
-                assert len(param.find('parameternamelist').findall('parametername')) == 1
 
-                name = param.find('parameternamelist').find('parametername')
+                # This is only for PHP, ignore for now
+                param_names = param.find('parameternamelist')
+                assert param_names.find('parametertype') is None
+
                 description = parse_desc(state, param.find('parameterdescription'))
-                if i.attrib['kind'] == 'param':
-                    out.params[name.text] = (description, name.attrib['direction'] if 'direction' in name.attrib else '')
-                else:
-                    assert i.attrib['kind'] == 'templateparam'
-                    out.templates[name.text] = description
+
+                # Gather all names (so e.g. `@param x, y, z` is turned into
+                # three params sharing the same description)
+                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 '')
+                    else:
+                        assert i.attrib['kind'] == 'templateparam'
+                        out.templates[name.text] = description
 
         elif i.tag == 'variablelist':
             assert element.tag == 'para' # is inside a paragraph :/
diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h
index 3d3d39d7..92fe3e19 100644
--- a/doxygen/test/compound_detailed/File.h
+++ b/doxygen/test/compound_detailed/File.h
@@ -136,6 +136,12 @@ merged and reordered.
 */
 template<class A, class B> void bar(int a, int b);
 
+/**
+@brief Function with one description for all params
+@param x, y, z Coordinates in 3D space
+*/
+void thisIsAShittyWayToPassAVectorButWhatever(float x, float y, float z);
+
 }
 
 namespace Eno {
diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html
index 7bc6775f..a89b6fb0 100644
--- a/doxygen/test/compound_detailed/namespaceFoo.html
+++ b/doxygen/test/compound_detailed/namespaceFoo.html
@@ -61,6 +61,12 @@
               int b)</span>
             </dt>
             <dd>A function with scattered docs.</dd>
+            <dt>
+              <span class="m-dox-wrap-bumper">void <a href="#a1e4e8c2c75da6e24d78c8a84e0cb3226" class="m-dox">thisIsAShittyWayToPassAVectorButWhatever</a>(</span><span class="m-dox-wrap">float x,
+              float y,
+              float z)</span>
+            </dt>
+            <dd>Function with one description for all params.</dd>
           </dl>
         </section>
         <section>
@@ -199,6 +205,33 @@
             </table>
 <p>This is a function that has the docs all scattered around. They should get merged and reordered.</p>
           </div></section>
+          <section class="m-dox-details" id="a1e4e8c2c75da6e24d78c8a84e0cb3226"><div>
+            <h3>
+              <span class="m-dox-wrap-bumper">void Foo::<wbr /></span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#a1e4e8c2c75da6e24d78c8a84e0cb3226" class="m-dox-self">thisIsAShittyWayToPassAVectorButWhatever</a>(</span><span class="m-dox-wrap">float x,
+              float y,
+              float z)</span></span>
+            </h3>
+            <p>Function with one description for all params.</p>
+            <table class="m-table m-fullwidth m-flat">
+              <thead>
+                <tr><th colspan="2">Parameters</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td style="width: 1%">x</td>
+                  <td>Coordinates in 3D space</td>
+                </tr>
+                <tr>
+                  <td>y</td>
+                  <td>Coordinates in 3D space</td>
+                </tr>
+                <tr>
+                  <td>z</td>
+                  <td>Coordinates in 3D space</td>
+                </tr>
+              </tbody>
+            </table>
+          </div></section>
         </section>
       </div>
     </div>
-- 
2.30.2