Doxygen 中的 Markdown 文件，两个谜题

Question

环境是 Microsoft Windows 10 中的 Doxygen 1.8.7。

我正在开发一个 Doxygen 项目，其中包含几个降价文件，它们都遵循这种模式：

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

我对此有两个问题。

首先，文件没有@} 来平衡第4 行的@{，但Doxygen 没有发出警告。这只是 Doxygen 中的一个错误或怪癖，还是由于某种我不明白的原因而有效？

其次，该文件产生（至少）两页输出。一个标题为yyy，包含第5 行及以下的文本，这很好。另一个标题为md_<d>_<dd>_<ddd>_xxx.html， 其中<d>_<dd>_<ddd>... 是从 repo 的主目录到文件的路径中的目录名称。这个只包含版权声明，没有用，看起来很愚蠢。

有没有办法让这个页面消失？

注意，我还没有弄清楚如何通过单击链接从项目主页访问“版权”页面。如果没有办法做到这一点，那么页面的存在就是微不足道的。但我假设因为 Doxygen 生成页面，它提供了 一些 方式来显示它，我还没有找到。

Answer 1

正如评论中已经指出的，1.8.7 版本有点旧（2014 年 4 月），当前的 doxygen 版本是 1.8.20。 此答案中的解决方案基于 doxygen 1.8.20，因为 1.8.7 它们在 1.8.7 中不起作用（在 1.8.17 中它们应该起作用）

问题中提到了2个问题

• 如果@{ 没有关闭@}，则不会发出警告。这可能不正确，但@{ 在@page 中没有任何意义。 这应该进一步调查，可能值得在 doxygen 问题跟踪器中添加一个新问题：https://github.com/doxygen/doxygen/issues/new/choose。。我刚刚将提议的补丁推送到 github（拉取请求 8060，https://github.com/doxygen/doxygen/pull/8060）。

• 删除“版权”
  在降价文件中，当第一个非空白行不是页面命令时（如@page \ @mainpage text\n====），doxygen 将添加一个@page 命令，文件名作为标题。有许多可能性可以“克服”这个问题。 Doxygen 有许多命令可以使内容与注释一样少，因此不会出现在输出中。它们是：

  • <!-- ....-> 即普通的 HTML 注释符号（也会从其他输出格式中删除该内容）
  • \cond [<label>] ...\endcond 如果 ` 评估为 false 或不存在，则不显示块的内容
  • \if <label> ...\endif 如果 ` 评估为假，则不显示块的内容
  • \noop ...命令后的一行文字不显示。

  这里的问题是他们没有删除页面引用（因为由于处理顺序，命令看不到非空行），为此有一个解决方案：

  • 使用里面的“comment”命令移动内容（至少在第一个@page like 命令之后的某个位置。所以解决方案可能如下所示：

    @page xxx1 yyy1
    <!--
    Copyright (c) 2016-2017, XYZ CORP. All rights reserved.
    -->
    
    Start of text1
    

看起来我前段时间已经创建了一个关于自动处理 <!--: https://github.com/doxygen/doxygen/pull/6909 的拉取请求

2020 年 9 月 29 日编辑拉取请求 https://github.com/doxygen/doxygen/pull/8060 已集成到 doxygen 的主版本中。