How to use Markdown pages and Doxygen groups?

2019-01-29 05:25发布

问题:

I'm writing a technical manual using Doxygen and Markdown. Markdown for simplicity of generating HTML, and Doxygen because of many years experience of using it for code and knowing how it can produce good cross-documentation with the \ingroup facility.

I'm failing to get the latter to work properly with Doxygen's handling of Markdown.

What I want to achieve is to write a fully descriptive training document but to be able to mark important sections and have Doxygen pull those out into a separate 'Tips' page (for example) for quick reference later.

These snippets illustrate the problem. All the files are .md and I have a separate mainpage.md which is working OK. The relevant MARKDOWN options are set YES in the doxyfile. the Groups are defined in a .h file using /** */ because I could not get then to behave reliably in .md files (that's probably related to this problem).

A 'group 1' block of text

@ingroup  group_01

# Group 01 MD heading

Text 1 for Group 1.  Mirum est notare quam littera gothica.

and one for group 2 text

@ingroup group_02

# Group 02 MD Heading

Text 1 for group 2. Lorem banana dolor sit amet elit.

and a file with info I want in group 1 and other parts in group 2

@ingroup group_01
@{

# Text 2 group 1

Text 2 for group 1. Duis autem vel eum iriure dolor.

@}

@ingroup group_02
@{

# T2G2 THIS NEVER APPEARS

Text 2 for group 2. Nibble liber tempor cum soluta nobis.

@}

What I am expecting is for the 'Modules' section to contain two entries for the two groups (which it does), and that the group 1/2 pages contain the text marked by @ingroup.

What I getting is that first seen @ingroup is being processed exactly as I expect, and Doxygen is correctly collating the various group entries on to one page. Text outside of that does not appear in the output at all. If I swap the order of the text blocks in the last file, the other block appears and the previously visible block disappears.

I get similar output failures if I don't use the @{ @} bracing and simply have @ingroup_01 and @ingroup_02. FWIW, @ingroup (group_01 group_02) seems to simply not work in a Markdown file.

What am I doing wrong?

Does anyone have alternative suggestions how to achieve my aims?

I'm using the latest released Doxygen 1.8.5. The Doxygen manual says nothing useful about this.

This question has some similarity to this one, but that's looking at the problem from the code perspective.

回答1:

It seems I'm doing nothing wrong. This answer, to a related question, reveals that this functionality is simply not supported by Doxygen 1.8.5 for markdown pages, but that the non-functionality is not (yet) flagged in the Doxygen manual in either the 'group' or 'markdown' pages.