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链接,然后再单击Go to the source code of this file.内部链接.我不太关心文件部分中的链接如何表现,尽管我宁愿让它们转到文件文档,就像默认情况下那样.

我不想在教程页面中使用\example任何一个包含源代码,因为它已经存在于单独解释的小部分中.

Answer 1

您可以采取不同的方法并使用或自动引用教程中的示例代码，而不是将读者重定向到任何地方。\include\snippet

我同意两步的效果\ref有点无聊，但即使一步一步地从教程文本中单独查看代码也会破坏读者的注意力。

根据“示例”中的代码量，您可以将其完整插入到 doxygen 输出中\include，也可以使用 引用教程页面中的关键部分\snippet。后者的优点是您可以将其分成散布在教程文本中的部分进行。

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

相关 Doxygen 手册部分请参见此处。

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