doxygen: support \section etc. in function documentation.

Not rendered into <section> tags as that breaks the style, it's just
basic <hX> tags. Also ensuring that \param, \return etc. are propagated
from there.

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index d1424a6651673f332421cdcb24429f43b1e193e7..ebd29f4b2ad36fdfa8ec8f412b97afc2870acaca 100644 (file)
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -224,9 +224,6 @@ amount of generated content for no added value.
     accompanied with corresponding tutorial page instead)
 -   :cpp:`inline` functions are not marked as such (I see it as an unimportant
     implementation detail)
--   ``@section``, ``@subsection`` etc. commands inside anything else than
-    top-level documentation of a class, namespace, file, directory, page or
-    module are not supported as the visual layout is not expecting such things
 -   The :ini:`CREATE_SUBDIRS` Doxyfile option is not supported. This option
     causes Doxygen to scatter the XML files across numerous subdirectories to
     work around limits of ancient filesystems. Implementing support for this

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 5a03f8f1449173a70b4122f82371c0b947e3423c..317e8a9f14a1da751642f2232c370f38de91ca39 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -656,38 +656,67 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
             has_block_elements = True
 
             parsed = parse_desc_internal(state, i)
-            assert parsed.section
-            assert not parsed.templates and not parsed.params and not parsed.return_value
+
+            # Render as <section> in toplevel desc
+            if state.parsing_toplevel_desc:
+                assert parsed.section
+                assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions
+
+                # Top-level section has no ID or title
+                if not out.section: out.section = ('', '', [])
+                out.section = (out.section[0], out.section[1], out.section[2] + [parsed.section])
+                out.parsed += '<section id="{}">{}</section>'.format(extract_id_hash(state, i), parsed.parsed)
+
+            # Render directly the contents otherwise, propagate parsed stuff up
+            else:
+                merge_parsed_subsections(parsed)
+                out.parsed += parsed.parsed
+
             if parsed.search_keywords:
                 out.search_keywords += parsed.search_keywords
 
-            # Top-level section has no ID or title
-            if not out.section: out.section = ('', '', [])
-            out.section = (out.section[0], out.section[1], out.section[2] + [parsed.section])
-            out.parsed += '<section id="{}">{}</section>'.format(extract_id_hash(state, i), parsed.parsed)
-
         elif i.tag == 'title':
             assert element.tag != 'para' # should be top-level block element
             has_block_elements = True
 
-            if element.tag == 'sect1':
-                tag = 'h2'
-            elif element.tag == 'sect2':
-                tag = 'h3'
-            elif element.tag == 'sect3':
-                tag = 'h4'
-            elif not element.tag == 'simplesect':
-                assert False # pragma: no cover
+            # Top-level description
+            if state.parsing_toplevel_desc:
+                if element.tag == 'sect1':
+                    tag = 'h2'
+                elif element.tag == 'sect2':
+                    tag = 'h3'
+                elif element.tag == 'sect3':
+                    tag = 'h4'
+                elif not element.tag == 'simplesect':
+                    assert False # pragma: no cover
+
+            # Function/enum/... descriptions are inside <h3> for function
+            # header, which is inside <h2> for detailed definition section, so
+            # it needs to be <h4> and below
+            else:
+                if element.tag == 'sect1':
+                    tag = 'h4'
+                elif element.tag == 'sect2':
+                    tag = 'h5'
+                elif element.tag == 'sect3':
+                    tag = 'h6'
+                elif not element.tag == 'simplesect':
+                    assert False # pragma: no cover
 
             # simplesect titles are handled directly inside simplesect
             if not element.tag == 'simplesect':
                 id = extract_id_hash(state, element)
                 title = html.escape(i.text)
 
-                # Populate section info
-                assert not out.section
-                out.section = (id, title, [])
-                out.parsed += '<{0}><a href="#{1}">{2}</a></{0}>'.format(tag, id, title)
+                # Populate section info for top-level desc
+                if state.parsing_toplevel_desc:
+                    assert not out.section
+                    out.section = (id, title, [])
+                    out.parsed += '<{0}><a href="#{1}">{2}</a></{0}>'.format(tag, id, title)
+
+                # Otherwise add the ID directly to the heading
+                else:
+                    out.parsed += '<{0} id="{1}">{2}</{0}>'.format(tag, id, title)
 
         elif i.tag == 'heading':
             assert element.tag == 'para' # is inside a paragraph :/

diff --git a/doxygen/test/contents_section_in_function/File.h b/doxygen/test/contents_section_in_function/File.h
index 1fb17128d00bd1866b6eb07cab575f711dcd78db..33a7dbc43035831cb61cf91ff99f40b976d54322 100644 (file)
--- a/doxygen/test/contents_section_in_function/File.h
+++ b/doxygen/test/contents_section_in_function/File.h
@@ -12,5 +12,20 @@
 ### A third-level header
 
 #### A fourth-level header
+
+@section foo-usage Usage
+
+This is usage.
+
+@subsection foo-usage-more More
+
+A subsection.
+
+@subsubsection foo-usage-more-more More.
+
+Mooore.
+
+@param bar A param.
+@return Does not return anything.
 */
-void foo();
+void foo(int bar);

diff --git a/doxygen/test/contents_section_in_function/File_8h.html b/doxygen/test/contents_section_in_function/File_8h.html
index 92a9f7559e28349ea428d44019b3f8eec5aa0c5b..3a6c4d8615d6058f5da3d5068fbb30fd73dffa78 100644 (file)
--- a/doxygen/test/contents_section_in_function/File_8h.html
+++ b/doxygen/test/contents_section_in_function/File_8h.html
@@ -38,19 +38,36 @@
           <h2><a href="#func-members">Functions</a></h2>
           <dl class="m-dox">
             <dt>
-              <span class="m-dox-wrap-bumper">void <a href="#ac07863d69ae41a4e395b31f73b35fbcd" class="m-dox">foo</a>(</span><span class="m-dox-wrap">)</span>
+              <span class="m-dox-wrap-bumper">void <a href="#adc5bb4b0f2fddd234994abbe97abb8b1" class="m-dox">foo</a>(</span><span class="m-dox-wrap">int bar)</span>
             </dt>
             <dd>A function.</dd>
           </dl>
         </section>
         <section>
           <h2>Function documentation</h2>
-          <section class="m-dox-details" id="ac07863d69ae41a4e395b31f73b35fbcd"><div>
+          <section class="m-dox-details" id="adc5bb4b0f2fddd234994abbe97abb8b1"><div>
             <h3>
-              <span class="m-dox-wrap-bumper">void </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#ac07863d69ae41a4e395b31f73b35fbcd" class="m-dox-self">foo</a>(</span><span class="m-dox-wrap">)</span></span>
+              <span class="m-dox-wrap-bumper">void </span><span class="m-dox-wrap"><span class="m-dox-wrap-bumper"><a href="#adc5bb4b0f2fddd234994abbe97abb8b1" class="m-dox-self">foo</a>(</span><span class="m-dox-wrap">int bar)</span></span>
             </h3>
             <p>A function.</p>
-<h4>A top-level header</h4><h5>A second-level header</h5><h6>A third-level header</h6><h6>A fourth-level header</h6>
+            <table class="m-table m-fullwidth m-flat">
+              <thead>
+                <tr><th colspan="2">Parameters</th></tr>
+              </thead>
+              <tbody>
+                <tr>
+                  <td style="width: 1%">bar</td>
+                  <td>A param.</td>
+                </tr>
+              </tbody>
+              <tfoot>
+                <tr>
+                  <th>Returns</th>
+                  <td>Does not return anything.</td>
+                </tr>
+              </tfoot>
+            </table>
+<h4>A top-level header</h4><h5>A second-level header</h5><h6>A third-level header</h6><h6>A fourth-level header</h6><h4 id="foo-usage">Usage</h4><p>This is usage.</p><h5 id="foo-usage-more">More</h5><p>A subsection.</p><h6 id="foo-usage-more-more">More.</h6><p>Mooore.</p>
           </div></section>
         </section>
       </div>