使用doxygen记录C ++概念？

Question

有没有方便的方法来记录doxygen中的C ++概念？我想要一些像this in the boost documentation这样的文档。

Answer 1

在与Doxygen挣扎之后，我终于找到了以下解决方案。

1. 为您的概念定义一个组：使用页面不合适，因为页面应指明其子页面（从树的顶部到底部），而组可能指示许多父组。这允许：

   • 将概念添加到一个（或多个）父概念，而不改变父概念本身（概念的细化/概括）
   • 将实体链接到多个概念，而不更改概念本身（例如，在向实现特定概念的库中添加类时）

   实施例

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

2. 使用一个参数定义自定义命令concept：

   ALIASES += concept{1}="@ingroup \1\n@par Implemented concepts:\n@ref \1"
   

   命令：

   • 将实体包含在定义概念的组中：实体将出现在概念的文档中（实体可能出现在几个组中）
   • 添加了一个Implemented concepts段落，提供了已实施概念的链接。

3. 表示特定的类/结构实现了这个概念：

   //!@brief Does things...
   //!@concept{measurement_functor_concepts}
   template <class T>
   struct my_struct: public std::unary_function<T, void> {};
   

我没有找到一种方法来生成一个很好的文档，比如Boost（有效表达式的好表等），但至少这个文档组织正确地分隔了一些东西。

Answer 2

您可以做的是定义名为Concept的自定义标记，然后您可以在描述时使用该标记。 example这是在Doxygen中使用别名机制，类似于：

ALIASES + =“con = \ xrefitem con \”Concept \“\”Concepts \“”

Answer 3

您可以使用\tparam对template parameters进行评论/记录。

Answer 4

我目前使用单独的手册页来记录概念，并使用\section和\subsection进行分组。然后，我可以使用\ref链接到它们。只要您在表中所描述的概念中描述概念，就可以使用此功能，但遗憾的是，不会启用指向单个部分的链接。

我还有一个别名来创建一个类型模型的概念列表。

Answer 5

我建议您考虑以下事项：

a）查看Boost Concept Checking库的文档。本文档向您展示如何创建一个可在代码中使用的类，以验证类型是否实际满足您要定义的概念的要求。你这样使用它：

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）所以现在你正是要求的！ - 您的概念的单独页面，以及从需要该概念的所有类中引用它的能力。