如何在Doxygen評論中包含.cpp文件的子集？

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

EDITED將第二個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

我想要包含它，但沒有#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（）。

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] 

• 然后像這樣使用snippet命令：

   /*!@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]
    }
}