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;
};
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
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? 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.
The executable doxygen is the main program that parses the sources and generates the documentation. See section Doxygen usage for more detailed usage information.
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.
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;
};
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;
};
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With