9

我正在尝试编写一些 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 文件,现在我几乎得到了正确的咒语。这几乎完全符合我的要求,是否有某种方法可以在没有标签的情况下使用 \until,并从 example.cpp 中删除最后的 // endcode 行?

4

3 回答 3

3

编辑将第二个参数添加到剪辑宏。

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

于 2009-10-19T16:22:39.413 回答
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();
    

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

于 2013-03-19T14:58:15.773 回答
0

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

编辑:为了澄清,我建议您将要包含的代码放在它自己的包含文件中,并#include在 CPP 文件中使用,然后\verbinclude在 doxygen 头文件中使用。

您的源文件如下所示:

#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]
    }
}
于 2009-10-19T13:38:04.817 回答