Question

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

我的example.cpp（我包含在.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文件，现在我几乎得到了正确的咒语。这几乎正是我想要的，有没有一种方法可以使用\直到没有标记，并从example.cpp中删除最后//结束代码行？

Answer 1

编辑以将第二个arg添加到剪辑宏。

这就是我所做的，这似乎对我有用。主要取自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

我想要包含它，但不要将#include包含在顶部。

我在我的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（）。

Answer 2

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();

这种方法易于设置，维护起来相当便宜。

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

如何在Doxygen评论中包含.cpp文件的子集？

3 个答案: