如何生成 rdoc 风格的可折叠代码段？

Question

我正在使用 Doxygen 为 C++ 项目创建内部文档。我让 Doxygen 包含方法等的来源，但这使得页面难以扫描。我希望它表现得像 rdoc 并将源隐藏在默认折叠的块中。

我认为HTML_DYNAMIC_SECTIONS 可能会让我这样做，但是，更改日志说该选项只会影响图表。

也许我可以通过编辑LAYOUT_FILE 来做到这一点？

无论如何，聪明的人，我怎样才能强制 Doxygen 生成可折叠的代码段？

Answer 1

如果包括[ing]方法等的来源，[...] 使页面难以扫描，你为什么不直接链接给它（SOURCE_BROWSER = YES）而不是包括它（INLINE_SOURCES = YES）？这将使页面更容易扫描和加载更快，并且源仍然可以访问（以多一个源页面加载为代价）。我猜这取决于您实际需要访问源代码的频率。

话虽如此，是一种生成可折叠代码段的方法（不过，您必须修改源代码并重新编译 Doxygen）：

• Doxygen 的 HTML 输出 are marked with two nested <div>s 中的可折叠部分如下：

    <div class="dynheader"><div class="dynsection">
    [collapsible section]
    </div></div>

• 包含的代码部分标记如下：<div class="fragment"><pre class="fragment">...</pre></div>

• 因此，要使包含的代码部分可折叠，您必须要么

  • 修改the code that generates 和<div class="fragment"><pre class="fragment">...</pre></div> 以生成<div class="dynheader"><div class="dynsection">...</div></div>（并可能调整一些css），或者
  • 更改扫描和折叠可折叠部分的javascript initDynSections() function，以将<div class="fragment"><pre class="fragment"> 识别为其中之一。

实现（或走SOURCE_BROWSER 路线:)）留给读者作为练习。祝你好运！

哦，如果您应该成功使用补丁，如果您可以 submit it 给 dimitri 以便他可以将其包含在未来的版本中，那就太好了。谢谢！

Answer 2

使用我选择的搜索引擎来到这里，我只想在此处留言，说明并非绝对需要修改任何 doxygen 源。

当被问到这个问题时，可能不可能embed pure html 使用htmlonly 标签，但考虑到这一点，可以创建可折叠的容器部分，滥用名为toggleVisibility 的函数

 function toggleVisibility(linkObj)
 {
   var base = $(linkObj).attr('id');
   var summary = $('#'+base+'-summary');
   var content = $('#'+base+'-content');
   var trigger = $('#'+base+'-trigger');
   var src=$(trigger).attr('src');
   if (content.is(':visible')===true) {
     content.hide();
     summary.show();
     $(linkObj).addClass('closed').removeClass('opened');
     $(trigger).attr('src',src.substring(0,src.length-8)+'closed.png');
   } else {
     content.show();
     summary.hide();
     $(linkObj).removeClass('closed').addClass('opened');
     $(trigger).attr('src',src.substring(0,src.length-10)+'open.png');
   } 
   return false;
 }

当前每次在文档根目录中的名为 dynsections.js 的文件中生成文档时都可用。

关于此代码，人们将了解能够使用 Javascript 从他/她自己的文档中创建可折叠代码的条件，从而避免此函数中的内部执行错误并防止进一步的 javascript 代码未被解释。

1. 具有唯一标识符id的dom元素
2. 另一个封装了唯一标识符id-summary的dom元素
3. 另一个封装了唯一标识符id-content的dom元素
4. 另一个封装了唯一标识符id-trigger的dom元素
5. id-trigger 元素必须包含至少 1 个字符的 src 属性
6. 主容器的class 属性无关紧要

考虑到这些条件，可以创建以下代码。

## <a href="javascript:toggleVisibility($('#example-div'))">Fold me</a>
## <div id="example-div">
##   <div id="example-div-summary"></div>
##   <div id="example-div-content">
##     <pre>
##       foo
##       bar
##     </pre>
##   </div>
##   <div id="example-div-trigger" src="-"></div>
## </div>
## @htmlonly <script type="text/javascript">$("#example-div").ready(function() { toggleVisibility($("#example-div")); });</script> @endhtmlonly

上面的 doxygen 代码用于使用 bash-doxygen 记录 bash 代码，因此它可能看起来与纯 doxygen 代码有点不同。已经描述了涉及 div 容器的第一部分，其中提到了适合函数 toggleVisibility 的源的条件，并使其可执行而不会出现任何错误，根据我们的需要调整 doxygen cmets。

这里使用的唯一 id 前缀是example-div。在第一行，有一个 hyperref 链接设置，可以直接使用 javascript 和一些 jQuery 代码展开一个部分。

剩下的就是最后的一个班轮。它包含需要运行的jQuery 脚本来初始折叠特定段。对于 bash-doxygen（可能还有其他语言），由于脚本的块作用域，块需要是单行的

通常 \htmlonly 和 \endhtmlonly 之间的内容按原样插入。当您想要插入一个具有块范围的 HTML 片段（如应该出现在

..

之外的表格或列表）时，这可能会导致 HTML 无效。您可以使用 \htmlonly[block] 使 doxygen 结束当前段落并在 \endhtmlonly 之后重新启动它。

正如在doxygen documentation 中注意到的那样，并在stackoverflow answer on including script tags in doxygen documentations 的右侧标记解决方案下方的评论。

感谢您的阅读。 希望这对来到这里的一些人有所帮助。