Doxygen：如何链接到带注释的源代码？

Question

我有一个非常简单的Main.cpp文件作为我的库的示例，并且我为它创建了一个教程页面。该页面大致如下：

/**
 *  @page simpleexample Simple Example
 *
 *  This example shows basic use. It is in \ref simple_example/Main.cpp.
 *
 *  And this is the description of the example.
 */

现在的作用是将simple_example/Main.cpp替换为指向该文件文档的链接。我希望它可以直接转到带注释的源代码。

是否有一种方法可以在不完全禁用每个文件的文档的情况下实现呢？我想要它，但我不喜欢人们需要点击Main.cpp链接，然后再点击转到此文件的源代码。链接。我并不太关心文件部分中的链接行为，尽管默认情况下它们应该转到文件文档。

我也不想使用\example将源代码包含在教程页面中，因为它已经以单独的小部分存在，并进行了逐个解释。

- the swine

---

创建了一个 RFE：https://github.com/doxygen/doxygen/issues/7945。 - Hi-Angel

Answer 1

我在我的旧代码中发现曾经使用过main.c_source来引用注释源代码（而不是文档！），但现在测试它并不起作用...

我为您提供的最佳解决方案是一个hack。使用HTML来引用注释源代码的实际.html文件。

<A HREF=main_8c_source.html><B> main.c annotated source </B></A>

根据我的观察，Doxygen遵循标准的重命名方案。点（.）被一致地更改为下划线加8（_8），并且在后面加上"_source"来引用源代码。大写字母被一致地更改为小写字母，并在前面加上下划线。例如MyFile.c会变成_my_file_8c。

你还需要设置CREATE_SUBDIRS = NO。如果设置为CREATE_SUBDIRS = YES，你就无法确定文件将位于哪个子目录中。

当然，这只是一个hack方法，你不能确定它在下一个版本中是否有效。你必须始终检查它是否仍然有效。也许可以向开发团队建议将其作为一个功能请求...

- Michael

---

不，这不是我想要的，而且我已经明确提到了。你提供的参考链接指向\example参考。我特别说过“我不想使用\example在教程页面内包含源代码”。谢谢你抽出时间来回答。 - the swine

啊...是的，我想我明白了，并且以前也做过这个。使用“/ref main_c_source”或类似的东西。我今天没有时间再编辑了，给我到明天吧... :) - Michael

昨天我在评论中提出的建议正是试图解决你想要的问题，即 **"_source"**。如果我将其放在代码引用中，我想这会更清晰：/ref main_c_source。是的，我知道它不起作用...但我也没有把它当作答案来推销，对吧？ - Michael

在配置文件中将 SOURCE_BROWSER = YES。 - Michael

不错，我没有想到。但不幸的是，这个项目非常庞大且不断增长，CREATE_SUBDIRS=YES 是必须的。不过我喜欢 HTML hack，我之前没想到过。 - the swine

Answer 2

与其把读者重定向到任何地方，你可以采用不同的方法，使用\include或\snippet自动引用教程中的示例代码。

我认为\ref的两步效果有些麻烦，但即使只是一个单一的步骤将代码从教程文本中分离出来，也会打断读者的注意力。

根据“示例”中代码的数量，你可以使用\include将其全部插入到doxygen输出中，或者你可以在教程页面上引用关键部分，使用\snippet。后者的优点是可以将它分成部分，夹杂在教程文本中间。

这两种方式都有好有坏，包含的示例被视为代码。这意味着目标文件中的doxygen注释将显示为代码而不是doxygen。这可能看起来不理想，但它可以帮助清楚地区分教程文本和示例文件。（话说，我只在教程页面上引用真实的代码样本时使用过snippet）

相关Doxygen手册章节在此。

我注意到你不想使用\example。我的方法略有不同（特别是\snippet），并且不会创建“示例”页面。这可能仍然不是你想要的，但我在这里提供它，以防对其他人有用。

- Cheeseminer

---

我已经在整个示例中使用了代码片段。我知道如何做到这一点。我只是想展示整个文件。我能想到的唯一解决方案是创建另一个页面并在那里使用\example。但这会在“真实”的代码列表中创建重复页面。无论如何，感谢您的努力。 - the swine

我最开始只是想写一个评论，但它变得有点长了，因此成为了“答案”。@theswine 我想到的另一件事（但我没有尝试过）是，如果你的例子只有一个，你是否可以使用\ref来链接函数/类，而不是文件。 - Cheeseminer

那并不能解决问题，\ref 会再次跳转到类文档而不是源代码。同样的问题也存在于那里。我的文件中没有包含任何类，只有几个函数展示了我的库的一个用法。它们已经作为片段全部被覆盖了，我只想为读者提供一个“全局视角”的链接。 - the swine

Answer 3

我尝试了一些可能性，对我有效的方法是为示例代码创建单独的页面。

 /**
 *  @page simpleexample Simple Example
 *
 *  This example shows basic use. It is in \ref simple_example_main.
 *
 *  And this is the description of the example.
 *
 *  @page simple_example_main Main.cpp
 *
 *  \include simple_example/Main.cpp
 */

我会帮助您翻译文本。以下是需要翻译的内容：

这将为您提供输出

此示例显示基本用法。它在 Main.cpp 中。

我发现直接从\include命令插入代码非常有用，因为它允许您在一页中插入多个源，并在代码文件之间有一些浮动文本。

为了使任何示例正常工作，您需要设置示例路径，在上面的示例中，它可能是以下内容：

EXAMPLE_PATH           = simple_example
EXAMPLE_PATTERNS       = *
EXAMPLE_RECURSIVE      = YES

- Patric Thysell