c++ - 使用 doxygen 记录 C++ 概念？

Question

<分区>

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. 使用一个参数定义自定义命令概念:

   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 中那样好的文档(用于有效表达式的漂亮表格等)，但至少这种文档组织可以正确地将内容分开。