Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to document a function object with doxygen?

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;
};
like image 980
deft_code Avatar asked Mar 05 '11 17:03

deft_code


People also ask

Can I use doxygen to document functions in C++?

Documenting functions in C++ with Doxygen - Stack Overflow I've got a project that I'm using Doxygen to generate documentation for. The documentation of the classes is fine, but I've also got some non-member functions that I use to create objects etc. I'd ... Stack Overflow About Products For Teams

How to create source code based documentation using Doxygen?

Creating A Sample Python Program In order to generate source code based documentation using Doxygen, we first need to have source code for it to use. We will create a main program, named doxygen_example.py, and a module, named sensors.py, that will be used by the program.

How Doxygen works?

How Doxygen works? Doxygen has some special syntaxes, which you can use in your comments in the code, and when you run this tool, it will parse out the documentation details from comments which follow the special Doxygen syntax. Doxygen supports several methods for incorporating documentation inside the comments.

What is the executable Doxygen program?

The executable doxygen is the main program that parses the sources and generates the documentation. See section Doxygen usage for more detailed usage information.


3 Answers

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.

like image 192
Fred Foo Avatar answered Sep 22 '22 09:09

Fred Foo


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;
};
like image 23
AJG85 Avatar answered Sep 20 '22 09:09

AJG85


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;
};
like image 42
jakar Avatar answered Sep 22 '22 09:09

jakar