c++doxygen

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


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


Solution

  • 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