Is there a non-obnoxious way to Doxygen a class header file?

Question

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'?

@πάνταῥεῖ It's autopopulated by my IDE so I just leave it in. — Izzo
You should probably add a virtual destructor anyway which would give you a great opportunity to define something in a .cpp file :-) — Dietmar Kühl
You can use the \param syntax instead of @param if you think the @ is ugly. — Thomas Matthews

Öö Tiib Öö Tiib · Accepted Answer · 2016-12-26T18:36:24

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

Is there a non-obnoxious way to Doxygen a class header file?

1 Answers