c++ Doxygen \example 和描述

Question

我正在使用doxygen version 1.8.8 来构建 C++ 文档。我对我的模板类进行了详细描述，如下所示：

/** A test class. Detailed description of the test class
 *  Usage:
 *  @code
 *    test a;
 *  @endcode
 */
template<>
class test
{
  //some class
};

并希望在名为 testexample.cpp 的文件中包含一个示例

如果我只是将@example 放在详细说明的末尾，则详细说明将应用于示例。

/** A test class. Detailed description of the test class
 *  Usage:
 *  @code
 *    test a;
 *  @endcode
 *  @example testexample.cpp
 *  An example of the test class.
 */
template<>
class test
{
  //some class
};

我怎样才能获得该类的详细描述和一个示例文件的链接，该示例文件以详细的方式显示该类的用法？

在@example 的 doxygen 示例中，他们引用了成员变量的示例。该示例链接到此成员函数。在这种情况下，这不是我希望实现的，因为我想展示如何在一个完整的示例中使用这个类，而不仅仅是在使用说明中。

Answer 1

Doxygen 处理示例的方式是代码示例是与常规文档分开的页面。所以@example 就像@page 或@module：它获取整个文档块并将其应用于示例页面。并且在该示例代码中使用的任何文档化实体都将在其文档中添加到该示例的链接。

所以你需要一个像这样的独立文档块：

/**
 *  @example testexample testexample.cpp
 *  An example of the test class.
 */

这不必与您的 test 类位于同一文件中。

Answer 2

在收到nicol的答复后，我通过以下方式实现了我想要的：

/** A test class. Detailed description of the test class
 *  Usage:
 *  @code
 *    test a;
 *  @endcode
 */
template<>
class test
{
  //some class
};
/**@example TestExample.cpp
 * Simple example of how to use the test class
 */

我已经尝试过这种方式，但是因为我没有在Doxyfile 中设置EXAMPLE_PATH，所以找不到示例，因此@example 标记变得无用。指定 EXAMPLE_PATH 后，一切都按预期工作。