使用doxygen记录枚举值

Question

假设：

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 的一个 Bug 吗？文档中的示例可以工作。（单击枚举名称不会带我到任何地方）

- Corey Richardson

---

我删除了我的回答，因为它不适用于C++11的enum class {}。 - drescherjm

这个问题或答案中的任何一种风格都适用于我使用 Doxygen 1.8.2。然而，它们中的 任何一个 都无法在我的同事机器上工作，同样是使用 Doxygen 1.8.2 -- 并且输入完全相同，直接从源代码控制获取。这里发生了一些神秘的事情。 - hmakholm left over Monica

啊，一点也不可怕。原来我同时安装了1.8.2和1.8.3.1版本，1.8.2在我的路径中排在第一位，而构建脚本使用的是完整路径到1.8.3.1版本的安装目录。 - hmakholm left over Monica

我遇到了一些奇怪的问题，有时候它们有记录，有时候没有。 - Matt Clarkson

Answer 1

在Doxygen 1.8.2中，以下两种方式都可以使用：

使用///

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

Using /*! ... */

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

Doxygen更新日志显示Doxygen 1.8.2支持enum class，因此我怀疑您的命令中可能存在一些小的语法问题。请将您的命令与上述两个代码片段进行比较，谢谢。

New features

Added support for C++11:

strongly typed enums, e.g.:
enum class E

- Masked Man

---

使用https://gist.github.com/c9b75f0a41525b2cbaf2，我得到了http://i.imgur.com/nvsD2.png的结果。当它是类的成员时，结果相同。你用那个得到了什么？它有什么不同？ - ember arlynx

我在这个解决方案中遇到了问题，当我为枚举成员分配值时也会出现问题。例如： enum class Positions : std::int8_t { UNDEFINED = -1, /*!< 值为-1 */ TOPLEFT = 0, /*!< 值为0 */ TOPRIGHT = 1, /*!< 值为1 */ BOTTOMLEFT = 2, /*!< 值为2 */ BOTTOMRIGHT = 3 /*!< 值为3 */ };在doxygen输出中，我得到了重复两次的字段。如何解决？ - madduci

@blackibiza，我希望我能帮助你解决这个问题（虽然我不能保证一定能解决），但是我很久以前就是一个 doxygen 狂热爱好者，自那以后已经转向更大更好的事物了。如果我有一个可行的 doxygen 设置，我会帮你查看的。在那之前，你最好提出一个新问题以获得更多的关注，并希望有其他人来查看它。还请注意，doxygen 的创建者和首席开发人员是活跃成员之一。 - Masked Man

太好了！请考虑创建一个新问题并自己回答它，以帮助未来遇到同样问题的人。 - Masked Man

@parvus 是的，这很糟糕，但直到现在，这是唯一有效的方法。 - madduci

Answer 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.
 */

}

这样，我就可以详细记录经常发生在我身上的事情。

---

正如Maxim Paperno在评论中提到的那样，\var，像\fn和其他一些命令，必须单独放在一行上。这可能是因为该命令后面的类型可能由多个C/C++关键字组成，很难将其与文档作者输入的消息区分开来。

- Alexis Wilke

---

谢谢。我也更喜欢这种风格。将文档放在维护源代码的位置，而不是头文件中。 - Ed of the Mountain

然而，如果你打算分发你编写的库的头文件，那么你的风格意味着该头文件没有注释。 - hmijail

这是一个选项，但我的观点是，如果您在头文件中包括了Doxygen，则头文件就是自文档化的，甚至可能不需要实际生成Doxygen文档。这就是为什么我更喜欢在头文件中记录其中的内容，并在实现中记录其余部分。 - hmijail

如果你不打算将文档与源代码保持紧密联系，那么使用Doxygen就没有意义了。你可以使用texinfo。Doxygen的整个目的是使文档与源代码保持紧密联系，这样希望文档能够及时更新。当某人在头文件中向枚举添加字段时，他们可能会忘记将其添加到位于另一个文件中的文档中！ - Jaap Versteegh

如果您注意Doxygen警告，您会发现它会告诉您所有未记录的内容。这就是我如何确保文档完整性。不幸的是，它无法生成错误，否则它将真正强制开发人员为其代码的100％编写文档...否则编译将失败。 - Alexis Wilke

Answer 3

以下样式适合我：

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

- Ramón J Romero y Vigil

---

这也是我使用的方法。请注意，只有在描述位于枚举值之前时才有效。 - BobMorane