9

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;
};
deft_code
  • 57,255
  • 29
  • 141
  • 224
  • I realize the first question is a bit subjective. I included it to allow for answers that just tell me I'm wrong and to just do it the normal way (with some justification I hope). The second question is much more to the point. – deft_code Mar 05 '11 at 17:44
  • This code is invalid, it should be `operator()(size_t y)` etc. – Fred Foo Mar 05 '11 at 17:56

3 Answers3

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.

Fred Foo
  • 355,277
  • 75
  • 744
  • 836
  • Are you suggesting I add `@param[in] y ...` to the class description? – deft_code Mar 05 '11 at 18:03
  • @deft_code: If you need `@param`, then the meaning is apparently not obvious. I tend not to use such features, relying on descriptive parameter names instead. – Fred Foo Mar 05 '11 at 18:06
  • Ideally, all functions are simple enough and parameters so well named that their purpose is obvious. However, that is not always the case. Just as sometimes I need to supply a slightly more in depth description of a function parameter I may need to elaborate on a function objects parameters. – deft_code Mar 05 '11 at 19:17
  • @deft_code: then document the functor's overall purpose in the class docs and only elaborate on the arguments in `operator()` docs. It's no use describing it further with "Call the functor" or similar, since that's obvious from the name. – Fred Foo Mar 05 '11 at 19:22
1

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;
};
albert
  • 8,285
  • 3
  • 19
  • 32
jakar
  • 1,031
  • 1
  • 11
  • 22
1

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;
};
AJG85
  • 15,849
  • 13
  • 42
  • 50