Let's say I'm attempting to use Doxygen to document the following class header. Note that this class is purely abstract, thus I don't have a corresponding source file.
#ifndef QMFBANK_H
#define QMFBANK_H
#include <memory>
class QMFBank
{
public:
QMFBank();
virtual void setInputReference(std::shared_ptr<double>) = 0;
virtual std::shared_ptr<double> getLowBandReference() = 0;
virtual std::shared_ptr<double> getHighBandReference() = 0;
virtual void clearFilter() = 0;
virtual void update() = 0;
};
#endif // QMFBANK_H
Using Doxygen, I place the following comments into the header file.
#ifndef QMFBANK_H
#define QMFBANK_H
#include <memory>
class QMFBank
{
public:
/**
* @brief Creates a quadrature mirror filter bank
* @param p_in A reference to an input source
*/
QMFBank();
/**
* @brief Sets the reference to the QMF banks input source
* @param p_in A reference to an input source
*/
virtual void setInputReference(std::shared_ptr<double>) = 0;
/**
* @brief Retrieves a reference to the lowpassband output
* @return Returns a shared pointer to the lowpassband output
*/
virtual std::shared_ptr<double> getLowBandReference() = 0;
/**
* @brief Retrieves a reference to the highpassband output
* @return Returns a shared pointer to the highpassband output
*/
virtual std::shared_ptr<double> getHighBandReference() = 0;
/**
* @brief Clears (zeros) the filter bank history
*/
virtual void clearFilter() = 0;
/**
* @brief Updates the filter bank.
* When this method is called, the filter bank will retrieve a new input and update its outputs
*/
virtual void update() = 0;
};
#endif // QMFBANK_H
However, I think this looks ugly. Yes the documentation will be quite readable within the Doxygen HTML, but it seems more difficult to read when trying to quickly reference something.
So my question: Is there a better way to write the Doxygen comments in this instance? Or is this pretty normal and I should just 'deal with it'?
You can use comments like /// to get rid of two most ugly lines with /** and */ and also you can remove that @brief. Without those it looks more-or-less like OK header file.
#ifndef QMFBANK_H
#define QMFBANK_H
#include <memory>
/// Comment about class itself too
class QMFBank
{
public:
/// Creates a quadrature mirror filter bank
QMFBank();
/// Sets the reference to the QMF banks input source
/// @param p_in A reference to an input source
virtual void setInputReference(std::shared_ptr<double> p_in) = 0;
/// Retrieves a reference to the lowpassband output
/// @return shared pointer to the lowpassband output
virtual std::shared_ptr<double> getLowBandReference() = 0;
/// Retrieves a reference to the highpassband output
/// @return shared pointer to the highpassband output
virtual std::shared_ptr<double> getHighBandReference() = 0;
/// Clears (zeros) the filter bank history
virtual void clearFilter() = 0;
/// Updates the filter bank.
/// When this method is called, the filter bank will retrieve
/// a new input and update its outputs
virtual void update() = 0;
};
#endif // QMFBANK_H