From bbb55becae9d175b2362530d788dced2758afcb0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 19 May 2018 10:54:00 +0200 Subject: [PATCH] doxygen: support \section etc. in function documentation. Not rendered into
tags as that breaks the style, it's just basic tags. Also ensuring that \param, \return etc. are propagated from there. --- doc/doxygen.rst | 3 - doxygen/dox2html5.py | 67 +++++++++++++------ .../test/contents_section_in_function/File.h | 17 ++++- .../contents_section_in_function/File_8h.html | 25 +++++-- 4 files changed, 85 insertions(+), 27 deletions(-) diff --git a/doc/doxygen.rst b/doc/doxygen.rst index d1424a66..ebd29f4b 100644 --- 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 5a03f8f1..317e8a9f 100755 --- 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
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 += '
{}
'.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 += '
{}
'.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

for function + # header, which is inside

for detailed definition section, so + # it needs to be

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}>{2}'.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}>{2}'.format(tag, id, title) + + # Otherwise add the ID directly to the heading + else: + out.parsed += '<{0} id="{1}">{2}'.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 1fb17128..33a7dbc4 100644 --- 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 92a9f755..3a6c4d86 100644 --- a/doxygen/test/contents_section_in_function/File_8h.html +++ b/doxygen/test/contents_section_in_function/File_8h.html @@ -38,19 +38,36 @@

Functions

- void foo() + void foo(int bar)
A function.

Function documentation

-
+

- void foo() + void foo(int bar)

A function.

-

A top-level header

A second-level header
A third-level header
A fourth-level header
+ + + + + + + + + + + + + + + + +
Parameters
barA param.
ReturnsDoes not return anything.
+

A top-level header

A second-level header
A third-level header
A fourth-level header

Usage

This is usage.

More

A subsection.

More.

Mooore.

-- 2.30.2