有没有一种方便的方法可以在 doxygen 中记录 C++ 概念?我想在 boost 文档中有这样的文档。
5 回答
在与 Doxygen 进行了一番挣扎之后,我终于找到了以下解决方案。
为您的概念定义一个组:使用页面并不合适,因为页面应该指示其子页面(从树的顶部到底部),而组指示可能有许多父组。这允许:
- 将概念添加到一个(或多个)父概念,而不改变父概念本身(概念的细化/概括)
- 在不改变概念本身的情况下将实体链接到多个概念(例如,将类添加到实现特定概念的库时)
例子
/*!@defgroup measurement_functor_concepts Measurement function objects * @ingroup generalconcepts * @{ * @par Description * blablabla * * @par Notations * Let @c F be the type of the function object, @c f an instance. * * @par Valid Expressions * - @c f function object is ... * - <b>f.result()</b> returns ... * @} */
concept
使用一个参数定义自定义命令:ALIASES += concept{1}="@ingroup \1\n@par Implemented concepts:\n@ref \1"
命令:
- 将实体包含在定义概念的组中:实体将出现在概念的文档中(实体可能出现在多个组中)
- 添加一个段落,
Implemented concepts
提供指向已实现概念的链接。
表明一个特定的类/结构实现了这个概念:
//!@brief Does things... //!@concept{measurement_functor_concepts} template <class T> struct my_struct: public std::unary_function<T, void> {};
我没有找到一种方法来生成像 Boost 中那样的好文档(有效表达式的好表等),但至少文档的这种组织可以正确地分离事物。
您可以做的是定义一个名为 Concept 的自定义标签,然后您可以按照您的描述使用它。这方面的一个例子是使用 Doxygen 中的别名机制,例如:
ALIASES += "con=\xrefitem con \"Concept\" \"Concepts\" "
您可以\tparam
用来评论/记录模板参数。
我目前使用单独的手册页来记录概念并将 with\section
和\subsection
. 然后,我可以使用 链接到它们\ref
。只要您在提供的链接中使用表格描述概念,这就会起作用,但遗憾的是不会启用指向单个部分的链接。
我还有一个别名来创建类型模型的概念列表。
我建议你考虑以下几点:
a) 查看 Boost 概念检查库的文档。本文档向您展示了如何创建一个可在您的代码中使用的类,以验证 at 类型实际上满足您要定义的概念的要求。你像这样使用它:
template<typename T>
my_class{
MyConcept(T); // provokes compile error if T does not match concept
T m_t;
};
仅供参考,用于创建概念检查类的元素与概念精简版提案之间存在一对一的对应关系。因此,当概念精简版真正起作用时,过渡应该很容易。
b) 现在使用 DOxygen 记录 MyConcept 检查类!!!
c) 在 my_class 文档中使用 DOxygen /tparam 来参考 MyConcept
c)所以现在你得到了你想要的东西!!!- 您的概念的单独页面,以及从需要该概念的所有课程中引用它的能力。