How to document a function object with doxygen?

Question

How should I document a function object (AKA functor) with doxygen? It feels misleading to just document it as a regular class. I find it much better to think of a function object as a function with a closure than a callable class.

Is there a way to document a function object that fits with my preferences?

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;
};

Answer 1

Give it class documentation, put the word functor in the first sentence (preferably as the first word) and skip the operator() documentation if the meaning is obvious.

Mind you: the meaning is often not obvious if operator() is overloaded.

Answer 2

You could use doxygen member groups to group all of your functors together. Maybe something like this would work:

/// @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;
};

Answer 3

Class documentation should be sufficient. Just describe the purposes and usage and clarify anything useful. Overly verbose documentation of the obvious can be avoided.

/*! \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;
};