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

Doxygen: How to link to annotated source code?

本文关键字：注释 源代码 链接 何链接 Doxygen      更新时间：2023-10-16

我的库有一个非常简单的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的教程页面中包含源代码，因为它已经在单独解释的小部分中了。

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

我给你的最好的解决方案是我们一个黑客。使用HTML引用注释源的实际.HTML文件。

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

根据我的观察，Doxygen遵循一个标准的重命名方案。"."始终更改为"_8"，并附加"_source"以引用源代码。大写字母始终改为小写，并在其前面加下划线。MyFile.c变为_my_file_8c

您还必须设置CREATE_SUBDIRS = NO。如果是CREATE_SUBDIRS = YES，那么你就不能真正确定文件将在哪个子目录中。

当然，作为一个黑客，你永远无法确定它在下一个版本中是否有效。你总是要反复检查它是否仍然有效。也许可以作为功能请求向他们建议。。。

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

我同意ref的两步效应有点麻烦，但即使是从教程文本中单独看代码的一步也会打断读者的注意力。

根据"示例"中的代码量，您可以使用include将其全部插入到doxygen输出中，或者使用snippet引用教程页面中的关键部分。后者的优点是，您可以在教程文本中穿插部分进行操作。

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

此处为Doxygen手册的相关章节。

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

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

 /**
 *  @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
相关文章：