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

对于我的库，我有一个非常简单的示例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\u example/Main.cpp

引用。我希望它直接转到带注释的源代码

有没有一种方法可以在不完全禁用每个文件文档的情况下执行此操作？我想拥有它，但我不喜欢人们需要单击Main.cpp链接，然后再单击

转到此文件的源代码。

链接一次。我不太关心文件部分中的链接的行为，尽管我宁愿让它们转到文件文档，就像它们默认做的那样

---

我也不想使用

\example

在教程页面中包含源代码，因为它已经存在于单独解释的小部分中。

您可以采取不同的方法，在教程中使用

\include

或

\snippet

自动引用示例代码，而不是将您的读者重定向到任何地方

我同意

\ref

的两步效果有点不切实际，但即使是从教程文本中单独看一步代码，也会破坏读者的注意力

根据“示例”中的代码量，您可以使用

\include

将其全部插入到doxygen输出中，也可以使用

\snippet

引用教程页面中的关键部分。后者的优点是，您可以在教程文本中穿插的部分中完成

这两者都有一个混合的好处，即所包含的示例被视为代码。这意味着目标文件中的doxygen注释将显示为代码，而不是doxygen。这可能看起来不可取，但它将有助于明确哪些是教程文本，哪些是示例文件。（也就是说，我自己只在教程页面中引用了真实的代码示例。）

相关的Doxygen手册章节

---

我注意到您不想使用

\example

。我的方法稍有不同（尤其是

\snippet

），并且没有创建“示例”页面。这可能仍然不是您想要的，但我在这里提供它，以防它对其他人有用。

我在我的旧代码中发现，我曾经使用

main.c_source

引用带注释的源代码（不是文档！），但现在测试它不起作用

我为你提供的最好的解决方案是黑客攻击。使用HTML引用带注释源的实际.HTML文件

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

根据我的观察，Doxygen遵循标准的重命名方案。“.”始终更改为“_8”，并在引用源代码时附加“_source”。大写字母始终改为小写，前面加下划线

MyFile.c

变成

\u我的文件\u 8c

您还必须设置

CREATE\u SUBDIRS=NO

。如果

CREATE\u SUBDIRS=YES

，则无法确定文件将位于哪个子目录中

---

当然，作为一个黑客，你永远无法确定它是否能在下一个版本中工作。如果它仍然有效，你必须反复检查。可能会将其作为功能请求向他们推荐…

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

 /**
 *  @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

---

我已经在整个示例中使用了代码片段。我知道怎么做。我只是想展示整个文件。我能想到的唯一解决办法是制作另一个页面并在那里使用

\example

。但这会以某种方式创建与“真实”代码列表重复的页面。不管怎样，谢谢你的努力。我确实刚开始写评论，但有点长，所以才有了“答案”@我唯一想到的另一件事（但我没有尝试过）是，您是否可以使用

\ref

而不是文件来创建函数/类（如果您的示例就是其中之一）。这不会解决问题，\ref将再次转到类文档，而不是源代码。同样的问题。我的文件不包含任何类，只有几个函数显示了我的库的一个用途。所有这些都已经包含在片段中了，我只是想给读者提供一个链接，让他们“看到大局”。不，这不是我想要的，我已经明确提到了。您提供的参考链接到

\example

参考。我特别说过“我不想在教程页面中使用

\example

”包含源代码”。谢谢你花时间回答。啊。。。是的，我想我明白了，而且我以前也这么做过。使用/ref main_c_源或类似的东西。今天没有时间编辑了，明天再给我…：）我在昨天的评论中建议的是，试图准确地解决您想要的问题。如果我把它放在代码引号里，我想它会更清楚：

/ref main\u c\u source

。是的，我知道它不起作用。。。但是我也没有把它当作答案来卖，是吗？在配置文件nice中，SOURCE_BROWSER=YES，我没有想到这一点。但不幸的是，该项目规模相当大且不断增长，必须创建_SUBDIRS=YES。虽然我喜欢HTML黑客，但我没有想到。。