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

Question

我正在尝试编写一些Doxygen注释块，并且我想包含代码示例片段。当然，我希望这些示例实际上可以编译，以便它们不会过时。

我的example.cpp（我在.h文件中\include的文件）看起来像这样：

#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行？

- Eric H.

---

你是否正确设置了doxyfile中的EXAMPLE_PATH？ - Éric Malenfant

是的。文本已包含，我只是在尝试找出一些咒语，以便我不必看到开头的三个#include。 - Eric H.

你看过 http://www.stack.nl/~dimitri/doxygen/commands.html#cmddontinclude 上的例子了吗？ - Éric Malenfant

如果您可以发布您尝试过的内容，那么可能会更容易一些。 - Éric Malenfant

关于您关于“endcode”注释的问题：我认为使用“不可能”的模式进行的\until操作将一直持续到文件结束。 - Éric Malenfant

是的，我尝试了\until xyzzy，但那行不通。现在我只会将//endcode移动到与最终闭合括号相同的行上。我还做了另一件事，就是将函数的代码拆分到一个独立的文件中，然后只需包含那个文件。然后我要构建示例的项目有些奇怪。哦，好吧，我想达到100%不可行。谢谢帮助！ - Eric H.

Answer 1

有一种非常强大的命令是 snippet。假设你有以下这个函数：

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

您想要添加文件的一部分 sthgTests/sthg_factory.cpp：

• Edit sthgTests/sthg_factory.cpp and add a tag around the part of the code you would like to appear in the documentation (say using a tag named test_factory) like this:

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

• Then use the snippet command like this:

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

这种方法易于安装，而且维护成本相对较低。

- Raffi

Answer 2

编辑以加入对剪贴板宏的第二个参数。

这是我所做的，似乎对我有效。 主要参考了EricM的提示....

我的源文件 Time_Limiter_example.cpp 是：

#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

void tl_demo_short () 
{
} //endcode

我想要包含它，但不想让 #includes 出现在顶部。

我在我的 Doxyfile 中定义了一个 ALIAS：

ALIASES += clip{2}="\dontinclude \1 \n \skipline \2 \n \until endcode"

在我的页眉中，我的注释看起来像这样：

/**
 * \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.
 *
 * \clip{Time_Limiter_example.cpp,tl_demo}
**/

这正是我想要的，包括从.cpp文件中仅使用函数tl_demo()。

- Eric H.

---

这只有在手动添加“endcode”注释的情况下才有效，因此应该使用@snippet（请参见另一个答案，它需要两个注释来标记，但不会让人感到困惑，并且您可以放心地更改函数名称）。 - Top-Master

Answer 3

我认为\verbinclude应该允许您将文件作为代码包含，而不必在最后一行放置// \endcode。

编辑：澄清一下，我的建议是将要包含的代码放入其自己的包含文件中，在CPP文件中使用#include，然后在doxygen头文件中使用\verbinclude。

您的源文件应如下所示：

#include "stdafx.h"
#include "../types_lib/Time_Limiter.h"
#include <vector>    
#include "Time_Limiter_example.inc"

文件 "Time_Limiter_example.inc" 然后可以只包含代码示例:

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]
    }
}

- cdiggins

---

没错，但这并不是我想要的，我想要的是仅包含文件的子集。 - Eric H.