c++ - 是否有一种不令人讨厌的方法来 Doxygen 类头文件？

Question

假设我正在尝试使用 Doxygen 来记录以下类 header 。请注意，该类是纯抽象的，因此我没有相应的源文件。

#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

使用 Doxygen，我将以下注释放入头文件中。

#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

但是，我认为这看起来很丑陋。是的，文档在 Doxygen HTML 中将非常可读，但在尝试快速引用某些内容时似乎更难阅读。

所以我的问题是:在这种情况下是否有更好的方法来编写 Doxygen 注释？还是这很正常，我应该“处理它”？

Answer 1

您可以使用像///这样的注释来摆脱带有/** 和*/的两行最难看的行，您也可以删除@brief。如果没有这些，它看起来或多或少像 OK 头文件。

#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