使用 doxygen 记录枚举值答案

【问题标题】：Documenting enum values with doxygen使用 doxygen 记录枚举值
【发布时间】：2012-11-24 23:43:02
【问题描述】：

给定：

namespace Foo {
    class Foo {
    public:
        /// Foo enum, possible ways to foo
        enum class Foo {
            /// Foo it with an A
            A,
            /// Foo it with a B
            B,
            /// Foo it with a C
            C
        }
    }
}

而使用doxygen -g 制作的默认 Doxyfile，我明白了：

我怎样才能得到枚举值的记录？我尝试使用///<等将评论放在成员之前/之后，但无济于事。这可能只是 doxygen 中的一个错误吗？文档中的示例有效。（单击枚举的名称不会带我到任何地方）

【问题讨论】：

我删除了我的答案，因为它不适用于 C++11。枚举类 {}
这个问题中的样式或答案都适用于 Doxygen 1.8.2。另一方面，没有一个在我同事的机器上工作，同样使用 Doxygen 1.8.2 - 并且具有来自源代码控制的相同输入。这里发生了一些令人毛骨悚然的事情。
（啊，一点也不可怕。原来我同时安装了 1.8.2 和 1.8.3.1，1.8.2 是我路径中的第一个，而构建脚本使用了完整路径1.8.3.1 安装）。
我遇到了一些奇怪的问题，有时它们是否被记录在案。

标签： c++ c++11 enums doxygen

【解决方案1】：

使用 Doxygen 1.8.2，以下两项都适用于我：

使用///

/// This is an enum class
enum class fooenum {
    FOO, ///< this is foo
    BAR, ///< this is bar
};

使用/*! ... */

/*! This is an enum class */
enum class fooenum {
    FOO, /*!< this is foo */
    BAR, /*!< this is bar */
};

doxygen changelog 表示 Doxygen 1.8.2 支持 enum class，所以我怀疑您的命令中可能存在一些小的语法问题。能否请您将您的命令与上述两个 sn-ps 进行比较？

新功能

添加了对 C++11 的支持：
strongly typed enums, e.g.:
enum class E

【讨论】：

与gist.github.com/c9b75f0a41525b2cbaf2 我得到i.imgur.com/nvsD2.png。当它是类的成员时，结果相同。你得到什么？有什么不同？
当我还为枚举成员赋值时，我遇到了这个解决方案的问题。例如： enum class Positions : std::int8_t { UNDEFINED = -1, /*!/ TOPLEFT = 0, /!/ TOPRIGHT = 1 , /!/ BOTTOMLEFT = 2, /!/ BOTTOMRIGHT = 3 /!
@blackibiza 我希望我能帮助你解决这个问题（虽然我不能保证我能够解决这个问题），但我很久以前是一个 doxygen 狂热者，并且已经转向从那时起更大更好的事情。如果我有一个有效的 doxygen 设置，我会看看。在那之前，你最好的办法是提出一个新问题来获得更多的知名度，并且你希望让其他人来看看它。另请注意，doxygen 的创建者和首席开发人员是active member。
太棒了！请考虑创建一个新问题并自己回答，以帮助将来偶然发现该问题的其他人。
@parvus 是的，这很糟糕，但直到现在，这可能是唯一可行的方法

【解决方案2】：

请注意，我个人讨厌有冗长的头文件（因为记录意味着至少要编写 2 或 3 行文档，而不是一个字，所以我通常没有足够的简短内容）所以我更喜欢记录在 .cpp 文件中。

为此，您可以使用 Doxygen 的 \var 功能。

所以标题是裸露的：

namespace Foo {
    class Foo {
    public:
        enum class Foo {
            A,
            B,
            C
        };
    };
}

.cpp 文件有：

namespace Foo {

/** \enum Foo::Foo
 * \brief Foo enum, possible ways to foo
 *
 * All the necessary details about this enumeration.
 */

/** \var Foo::A
 * \brief Foo it with an A
 *
 * When you use A... etc.
 */

/** \var Foo::B
 * \brief Foo it with a B
 *
 * When you use B... etc.
 */

/** \var Foo::C
 * \brief Foo it with a C
 *
 * When you use C... etc.
 */

}

这样，我可以真正详细地记录我经常发生的事情。

【讨论】：

谢谢。我也比较喜欢这种风格。将文档放在您维护源 not 的标题中。
但是，如果您要分发您编写的库的头文件，您的样式意味着头文件没有 cmets。
这是一个选项，但我的意思是，如果您将 Doxygen 包含在标题中，那么标题是自记录的，以至于您甚至可能不需要实际生成 Doxygen 文档。这就是为什么我更喜欢在标题中记录其中的任何内容，并将其余部分记录在实现中。
如果您不打算将文档保存在源代码附近，那么使用 Doxygen 恕我直言是没有意义的。你可以只使用texinfo。 Doxygen 的全部意义在于保持文档接近源，因此希望文档保持最新。当有人在标题中向您的枚举添加字段时，他们可能会忘记添加到驻留在另一个文件中的文档中！
@JaapVersteegh 如果您注意 Doxygen 警告，您会发现它会告诉您所有未记录的内容。这就是我可以确保文档完整的方式。不幸的是，它不能产生错误，但那样它真的会迫使 devops 为他们的代码 100% 编写文档......否则编译会失败。

【解决方案3】：

以下风格适合我：

enum class Foo {
  /**Foo it with A*/
  A,
  /**Foo it with B*/
  B
}

【讨论】：