c++ - 如何在 Doxygen 注释中包含 .cpp 文件的子集？

Question

我正在尝试编写一些 Doxygen 注释 block ，并且我想包含示例代码片段。当然，我希望示例能够实际编译，这样它们就不会过时。

我的 example.cpp(我\include 在 .h 文件中)看起来像这样:

#include "stdafx.h"

#include "../types_lib/Time_Limiter.h"
#include <vector>

void tl_demo () {
    // scarce will be a gate to control some resource that shouldn't get called
    // more than 10 times a second
    Time_Limiter scarce (10);

    // here's a bunch of requests
    std::vector<int> req (500);

    for (size_t i=0;i<req.size ();i++) {
        scarce.tick ();
        // once we get here, we know that we haven't ticked
        // more than 10 times in the last second.

        // do something interesting with req[i]
    }
}

// endcode

我的头文件(我正在运行 Doxygen)如下所示:

/**
 * \ingroup types_lib
 *
 * \class   Time_Limiter
 *
 * \brief   Thread safe gate used to control a resource (such as an internet quote service) that has a limit on how often you can call it.
 *
 * \dontinclude Time_Limiter_example.cpp
 * \skipline void
 * \until endcode
 * 
**/

我想让 doxygen 只包含从“void demo”开始到文件末尾的内容(但没有//endcode)。

我尝试过使用\dontinclude 和\skip、\skipline 和\until，但我无法完全找出正确的咒语。

编辑:包括我的 .h 文件，现在我几乎得到了正确的咒语。这几乎完全符合我的要求，是否有某种方法可以在没有标记的情况下使用\until，并从 example.cpp 中删除最后//endcode 行？

Answer 1

snippet 命令是相当强大的。假设您有这样的功能:

/*!@brief Factory
 *
 * Creates sthg
 */
sthg* Create();

并且您想添加文件 sthgTests/sthg_factory.cpp 的一部分:

• 编辑 sthgTests/sthg_factory.cpp 并在您希望出现在文档中的代码部分周围添加一个标签(例如使用名为 test_factory 的标签>) 像这样:

  //! [test_factory]
  void test_factory()
  {
    // code here
  }
  //! [test_factory]
  

• 然后像这样使用代码段命令:

  /*!@brief Factory
   *
   * Creates sthg
   * @snippet sthgTests/sthg_factory.cpp test_factory
   */
  sthg* Create();
  

此方法易于设置且维护成本较低。