19

我有一个 main.cpp，其中包含一个结构、一些全局常量和一个主函数。

我运行了 doxygen，我在输出 index.html 中获得的唯一文档是我的结构。

我希望 doxygen 也将我的 main() 记录到 index.html 文件中。我做错了什么？

    /// Definition of Pi
    const auto Pi = 3.141592653589793238462643383279502884197169399;

    /// \struct myStruc
    /// \brief myStruc description
    ///
    struct myStruc
    {
         /// Comments inside myStruc
    };

    /// \file

    /// \brief  Main function
    /// \param  argc An integer argument count of the command line arguments
    /// \param  argv An argument vector of the command line arguments
    /// \return an integer 0 upon exit success
    int main(int argc, char** argv)
    {
        /// Comments I would like to be documented in as well
        return 0;
    }
4

4 回答 4

29

这是因为您正在记录一个全局对象，默认情况下 doxygen 不记录该对象。从doxygen 手册（强调我的）：

要记录 C++ 类的成员，您还必须记录该类本身。命名空间也是如此。要记录全局 C 函数、typedef、枚举或预处理器定义，您必须首先记录包含它的文件（通常这将是一个头文件，因为该文件包含导出到其他源文件的信息）。

让我们重复一遍，因为它经常被忽略：要记录全局对象（函数、typedef、枚举、宏等），您必须记录定义它们的文件。换句话说，至少必须有一个

/*! \file */

或一个

/** @file */

此文件中的行。

因此，请尝试将上述两行之一添加到您的 main.cpp 文件中。

于 2012-08-20T16:41:25.773 回答
4

确保HIDE_IN_BODY_DOCS设置为NO并使用如下内容：

/// \file

/// \brief  Main function
/// \param  argc An integer argument count of the command line arguments
/// \param  argv An argument vector of the command line arguments
/// \return an integer 0 upon exit success
int main(int argc, char** argv)
{
  /// Comments I would like to be documented in as well
  return 0;
}
于 2012-08-20T17:19:57.270 回答
2

对我来说，我必须确保我有这一套：

SHOW_FILES = 是

您的所有全局函数都将显示在每个文件内的“文件”选项卡中。此外，如果您在代码顶部定义了 @file 或 \file ，它也会有所帮助。

于 2013-08-03T08:47:03.287 回答
0

来自“其他地方的文档”部分的在线手册：http: //www.doxygen.nl/manual/docblocks.html#specialblock

“Doxygen 允许您将文档块放在几乎任何地方（例外是在函数体内部或普通 C 样式注释块内）。”

这是有道理的，因为通常不需要函数如何工作（其实现）的本质。我相信 doxygen 的目的是帮助编写易于搜索的文档，以允许编码人员找到事物的位置并查找它们的作用（以及传递给它的参数、返回的内容等）以学习如何使用它们，但不是它的实际实现方式。这需要实际查看函数源（也可以在 doxygen 生成的文件中找到）。另外，如果您注意到，所有示例（我认为）都在头文件中显示文档，这些文档缺少任何实现，这使我相信文档是针对头文件的，但是该工具使您可以灵活地放入源文件也是如此。

无论如何，这就是我的看法。有人有不同的想法吗？

于 2013-03-12T23:21:55.603 回答