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的两步效果有点偏僻，但即使只需要一步就可以从教程文本中单独查看代码会打破读者的注意力。

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

这两者都有混合的祝福，包含的样本被视为代码。这意味着目标文件中的doxygen注释将显示为代码而不是doxygen。这似乎是不合需要的，但它有助于明确哪个是教程文本，哪个是示例文件。（也就是说，我自己只使用snippet来引用教程页面中的实际代码示例。）

相关的Doxygen手册部分here。

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

Answer 2

我在旧代码中发现我曾使用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那么你无法确定该文件将在哪个子目录中。

当然，作为一个黑客，你永远无法确定它是否会在下一个版本中发挥作用。如果它仍然有效，你将不得不进行双重检查。也许建议它作为功能请求......

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 命令插入代码非常有用，因为它允许您每页插入多个源，并且在代码文件之间有一些浮动文本。 / p>

为了使任何示例都能正常工作，您需要设置示例路径，在上面的示例中，它可能类似于

EXAMPLE_PATH           = simple_example
EXAMPLE_PATTERNS       = *
EXAMPLE_RECURSIVE      = YES

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

3 个答案: