Markdown files in Doxygen, two puzzles

0
votes

The environment is Doxygen 1.8.7 in Microsoft Windows 10.

I'm working on a Doxygen project that includes several markdown files, which all follow this pattern:

  1  Copyright (c) 2016-2017, XYZ CORP. All rights reserved.
  2
  3  @page xxx yyy
  4  @{
  5    Start of text
         .
         .
         .
       End of text

I've got two questions about this.

First, the file has no @} to balance the @{ on line 4, yet Doxygen issues no warning. Is this just a bug or quirk in Doxygen, or is it valid for some reason I don't understand?

Second, this file produces (at least) two pages of output. One is titled yyy and contains the text from lines 5 and following, and that's fine. The other is titled md_<d>_<dd>_<ddd>_xxx.html, where <d>_<dd>_<ddd>... are the names of the directories in the path from the repo's home directory to the file. This one contains nothing but the copyright notice, which is useless and looks stupid.

Is there a way to make this page go away?

Note, I haven't figured out how to reach the "copyright" page from the project's home page by clicking links. If there's no way to do that, then the page's existence is trivial. But I assume that because Doxygen generates the page, it provides some way to display it, which I just haven't found yet.

1
markdowndoxygen
Sure you are using doxygen 1.8.7 (April 2014), the current version is 1.8.20... – albert

1 Answers

0
votes

As already noted in the comment the version 1.8.7 is a bit old (April 2014) and the current doxygen version is 1.8.20. The solutions in this answer are based on doxygen 1.8.20 as for 1.8.7 they won't work in 1.8.7 (in 1.8.17 they should work)

In the the question there are 2 problems mentioned

  • no warning in case of @{ without closing @}. This is probably not correct but @{ has no meaning in a @page anyway. This should be investigated further and is probably worth a new issue in the doxygen issue tracker: https://github.com/doxygen/doxygen/issues/new/choose .. I've just pushed a proposed patch to github (pull request 8060, https://github.com/doxygen/doxygen/pull/8060).

  • the removal of the "copyright"
    in a markdown file when the first non blank line isn't a page command (like @page \ @mainpage text\n====) doxygen will add a @page command with the name of the file as title. There are a number of possibilities to "overcome" this problem. Doxygen has a number of commands that make the contents more as less as comment and will thus not show up in the output. These are:

    • <!-- ....-> i.e. the normal HTML comment signs (will also remove the that content from the other output formats)
    • \cond [<label>] ...\endcond in case ` evaluates to false or is not present the content of the block is not shown
    • \if <label> ...\endif in case ` evaluates to false the content of the block is not shown
    • \noop ... the one line text after the command is not shown.

    The problem here is that they don't remove the page reference (as the commands are not seen non blank lines due to the order of processing), to accomplish this there is a solution:

    • move the content with the "comment" commands inside (at least somewhere after the first @page like command. So a solution could look like: 
      @page xxx1 yyy1
<!--
Copyright (c) 2016-2017, XYZ CORP. All rights reserved.
-->

Start of text1

Looks like I already created some time ago a proposed pull request regarding the automatic handling of <!--: https://github.com/doxygen/doxygen/pull/6909

Edit September 29 2020 The pull request https://github.com/doxygen/doxygen/pull/8060 has been integrated into the master version of doxygen.