是否有 non-obnoxious 方法将 Doxygen 生成 class header 文件？

Question

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

#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，我将以下注释放入 header 文件。

#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 注释？还是这很正常，我应该 'deal with it'？

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

是否有 non-obnoxious 方法将 Doxygen 生成 class header 文件？

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

c++

doxygen