Is there a trick to reduce the amount of redundant comments needed to fully cover Doxygen?

Question

As part of documenting my C ++ codebase, I am trying to get full Doxygen coverage - that is, I want all my (hundreds) of header files to have well-formed Doxygen comments for all of their public APIs, so that I can run Doxygen on the codebase database and do not see warnings about the warning "Warning: blah is not documented."

In general, this is just a matter of going through and documenting the material, but I noticed that I keep repeating the same text for each class. For example, I have many examples in essence:

/** The Foo class represents blah blah blah */ class Foo { public: /** Default constructor */ Foo(); /** Copy constructor * @param rhs the object to make this object a copy of. */ Foo(const Foo & rhs); /** Destructor */ ~Foo(); /** Equality operator. * @param rhs the object to compare against. * @returns true iff this object and (rhs) are equal. */ bool operator == (const Foo & rhs) const; /** Inequality operator. * @param rhs the object to compare against. * @returns true iff this object and (rhs) are not equal. */ bool operator != (const Foo & rhs) const; /** Assignment operator * @param rhs the object we should copy our state from * @returns a reference to *this */ Foo & operator = (const Foo & rhs); [...] } 

These comments are (usually) more or less exactly the same for each class, because these functions / operators almost always work the same for each class. Indeed, for copy operators or constructors that behaved in some other way, this would be a dubious design pattern, as C ++ programmers usually expect operators to work the same for each class.

My questions are: is there any trick by which I can tell Doxygen to automatically generate reasonable documentation for these things (for example, through some kind of template or macro) without my manually entering this text over and over again? This would significantly reduce the amount of text that I had to enter and maintain, and it also de-cluttered my header files, allowing me to remove “no duh” comments so that the reader could more easily find comments that offer real insight.

Answer 1

There are several commands for copying documentation:

\copydoc \copybrief \copydetails

Doxygen help offers the following syntax:

 /*! @copydoc MyClass::myfunction() * More documentation. */ 

This allows you to copy documentation from one class to another. Sometimes I only create a documentation class that does not compile as a standard place to output documentation from the rest of the project.