有没有一种不令人讨厌的方法来 Doxygen 类头文件？

Question

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

#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

Answer 2

我参与过几个团队项目，其书面规则明确是将所有 Doxygen 函数头移至 .cpp 文件中。

它不会注释 .hpp 文件中的成员函数，但您的 IDE 将为您获取文档，尤其是在 JetBrains 的情况下。主要思想是，除了最新的 IDE，您不应该使用其他任何东西来编写“真实项目”。

.hpp 仍然包含 Doxygen 文件和类头，但您可以快速扫描成员列表，并最终得到比 .hpp 更长的实现文件。另一方面，它在 .cpp 内创建“自然间隔”，并以某种方式保留读取或写入代码的文档详细信息（@usage、@details）。

我知道它与我习惯阅读的大多数开源项目（特别是 ITK）相矛盾，但我捍卫这样的观点：.hpp 不应该是详细的手册，而应该是类和目的的简明清单。其界面。可以有更好的方法，请随时教我顺便说一句。