如何用 doxygen 记录函数对象？答案

【问题标题】：How to document a function object with doxygen?如何用 doxygen 记录函数对象？
【发布时间】：2011-07-09 12:00:00
【问题描述】：

我应该如何用 doxygen 记录一个函数对象（AKA 函子）？仅将其记录为常规课程会产生误导。我发现将函数对象视为具有闭包的函数比可调用类要好得多。

有没有办法记录符合我偏好的函数对象？

class Adder
{
public:
   Adder( size_t x ) :
      m_x(x)
   { }

   size_t operator () ( size_t y ) const
   {
      return m_x + y;
   }

private:
   const size_t m_x;
};

【问题讨论】：

我意识到第一个问题有点主观。我把它包括在内是为了让答案告诉我我错了，并以正常的方式去做（我希望有一些理由）。第二个问题更重要。
此代码无效，应为operator()(size_t y)等

标签： c++ doxygen functor function-object

【解决方案1】：

给它类文档，把词functor放在第一句（最好作为第一个词），如果意思很明显，跳过operator()文档。

请注意：如果 operator() 过载，其含义通常不明显。

【讨论】：

你是否建议我在类描述中添加@param[in] y ...？
@deft_code：如果你需要@param，那么意思显然不明显。我倾向于不使用此类功能，而是依赖描述性参数名称。
理想情况下，所有函数都足够简单，参数命名得很好，它们的目的是显而易见的。然而，情况并非总是如此。就像有时我需要对函数参数提供更深入的描述一样，我可能需要详细说明函数对象的参数。
@deft_code：然后在类文档中记录函子的总体用途，并仅详细说明operator() 文档中的参数。用“调用函子”或类似的词来进一步描述它是没有用的，因为这从名称中很明显。

【解决方案2】：

类文档应该足够了。只需描述目的和用法并澄清任何有用的内容。可以避免过于冗长的显而易见的文档。

/*! \brief Adder functor
 *
 *  Returns size_t sum of const member and parameter
 */
class Adder
{
public:
   //! Construct with constant value for subsequent sums
   Adder( size_t x ) :
      m_x(x)
   { }

   //! Call with value to compute with constant
   size_t operator () ( size_t y ) const
   {
      return m_x + y;
   }

private:
   const size_t m_x;
};

【讨论】：

【解决方案3】：

您可以使用 doxygen member groups 将所有仿函数组合在一起。也许这样的事情会起作用：

/// @name Functors
/// @{

class Adder;

/// @}

/// Functor that adds a set value to its argument when called.
class Adder
{
public:
   Adder( size_t x ) :
       m_x(x)
   { }

   size_t operator () ( size_t y ) const
   {
      return m_x + y;
   }

private:
   const size_t m_x;
};

【讨论】：