标签: doxygen

我的团队开始使用 doxygen 记录我们的 C 代码，特别关注我们的公共 API 标头。doxygen 中似乎有很多灵活性和不同的特殊命令，这很棒，但如果没有反复试验，就不清楚什么是好事，什么是坏事。

您最喜欢的标记代码的方式是什么？您必须做什么和不应该做什么？
请提供您的重要提示，每个答案一个，以方便投票。

我希望定义 API 文档的整个方法，包括提供一个模板来让团队的其他成员开始。到目前为止我有这样的事情：

/**
 * @file   example_action.h
 * @Author Me (me@example.com)
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing. …

一个Xcode中5的新功能是一种特殊的注释语法来记录自己的代码的能力.格式类似于doxygen,但似乎只支持这些功能的子集.

支持哪些命令,哪些命令不支持？
他们的任何用法与doxygen有什么不同？

我是一般编程的新手,所以我决定从C++中创建一个简单的向量类开始.但是我想从一开始就养成良好的习惯,而不是稍后尝试修改我的工作流程.

我目前只有两个文件vector3.hpp和vector3.cpp.随着我对一切事物越来越熟悉,这个项目将慢慢开始增长(使其更像是一般的线性代数库),因此我希望采用"标准"项目布局,以便以后更轻松.所以在环顾四周后,我发现了两种组织hpp和cpp文件的方法,第一种方法是:

project
??? src
    ??? vector3.hpp
    ??? vector3.cpp

第二个是:

project
??? inc
?   ??? project
?       ??? vector3.hpp
??? src
    ??? vector3.cpp

你会推荐哪个？为什么？

其次,我想使用Google C++测试框架对我的代码进行单元测试,因为它看起来相当容易使用.你认为在我的代码捆绑这一点,例如inc/gtest或contrib/gtest文件夹？如果捆绑了,您是否建议使用fuse_gtest_files.py脚本来减少数量或文件,或保留原样？如果没有捆绑,这个依赖是如何处理的？

在编写测试时,这些测试通常是如何组织的？我想为每个类创建一个cpp文件(test_vector3.cpp例如),但是所有编译成一个二进制文件,以便它们可以轻松地一起运行？

由于gtest库通常是使用cmake和make构建的,所以我认为我的项目也可以像这样构建吗？如果我决定使用以下项目布局:

??? CMakeLists.txt
??? contrib
?   ??? gtest
?       ??? gtest-all.cc
?       ??? gtest.h
??? docs
?   ??? Doxyfile
??? inc
?   ??? project
?       ??? vector3.cpp
??? src
?   ??? vector3.cpp
??? test
    ??? test_vector3.cpp

如何CMakeLists.txt才能看到它只能构建库或库和测试？我也见过很多有a build和a …

我使用Doxygen为我的SDK制作了文档.它包含文件,名称空间,类,类型等的列表 - 我在代码中作为Doxygen注释放置的所有内容.现在我想写一些关于SDK(介绍类型)的一般信息,它与任何代码元素都没有直接关系.我想将此介绍放在文档起始页面上.我怎样才能做到这一点？

常识告诉Doxygen注释块必须放在头文件中,其中包含类,结构,枚举,函数和声明.我同意这是一个合理的论据,这些库意味着在没有源的情况下进行分发(只有头和带有目标代码的库).

但是......当我正在开发一个公司内部(或者作为我自己的副项目)库时,我一直在考虑完全相反的方法,该库将与其完整的源代码一起使用.我建议将大的注释块放在实现文件(HPP,INL,CPP等)中,以免混乱标题中声明的类和函数的接口.

优点:

• 头文件中的杂乱性较小,只能添加功能分类.
• 使用Intellisense时预览的注释块不会发生冲突 - 这是我在.H文件中有一个函数的注释块并在同一.H文件中使用其内联定义时观察到的一个缺陷但包含在.INL文件中.

缺点:

• (显而易见的一个)注释块不在声明所在的头文件中.

那么,您的想法和建议是什么？

我有一个R使用的包roxygen2.它有一些C代码/src,我刚开始使用Doxygen.有没有办法组合文档,或集成编译与roxygen2？在哪里放置C代码文档的"最佳实践" ？

谷歌搜索roxygen2和doxygen主要导致roxygen类似于doxygen结果.我找到了一些包含Doxyfiles的软件包,但没有一致的组织.例如,lme4 inst/doc/Doxyfile输出到源目录doxygen外部的文件夹lme4.在Matrix的根目录中还有一个Doxyfile(但在以前的版本中是这样的inst.此文档也导出到包目录之外.

是否有任何理由不在C包中包含文档,或者为什么Doxygen在R包中很少使用,尽管广泛使用C？

更新:查看相关的roxygen2功能请求

我喜欢doxygen来创建C或PHP代码的文档.我有一个即将推出的Python项目,我想我记得Python没有/* .. */评论,并且还有自己的自我文档工具,这似乎是pythonic的文档方式.

由于我熟悉doxygen,我如何使用它来生成我的Python文档？有什么特别需要注意的吗？

我一直在寻找一些描述如何使用doxygen生成简单类图的材料,但却找不到.有人可以帮忙吗？

我需要从一组C++文件中创建如下所示的图表.

如果有更好的工具来实现这一目标,请告诉我.

我需要为我的工作场所实施文档生成解决方案,并将其缩小到标题中提到的三个.我已经能够在这些解决方案之间进行正式比较的方式中找到很少的信息,我希望那些在上述一个或多个方面有经验的人可以权衡:

以下是我从初次传球中收集到的内容:

HeaderDoc优点:与苹果公司现有的文档一致,与制作苹果文档集的兼容性
HeaderDoc缺点:难以修改行为,项目没有积极处理,许多人已经转离它(意味着必须有一些不足之处,尽管我无法量化它).

Doxygen Pros:活跃支持社区b/c广泛使用基础,非常可定制,大多数输出​​类型(如乳胶等)
Doxygen缺点:工作使其外观/行为与apple docs一致,与apple docsets的兼容性并不那么简单

AppleDoc专业人士:看起来与苹果现有的文档一致,与制作苹果文档集的兼容性,
AppleDoc缺点:有关typedef,枚举和函数文档的问题,正在积极开发中

这听起来准确吗？我们理想的解决方案将:

• 苹果Objective-c类参考的一致外观
• 能够选项单击以从Xcode中提取文档引用,然后链接到doc(就像苹果的类)
• 智能处理类别,扩展等(甚至是苹果类的自定义类别)
• 能够创建我们自己的参考页面(比如这个页面:Loading ...可以包含图像,并且可以无缝地链接生成的类引用,就像apple的UIViewController类引用链接到链接页面一样.
• 易于运行的命令行命令,可以集成到构建脚本中
• 优雅地处理非常大的代码库

根据以上所有信息,上述任何一种解决方案明显优于其他解决方案吗？任何建议或信息,将非常感激.

我刚从CACM的一篇文章中了解到,Doxygen也使用Java(以及其他几种语言).但是Java已经有了Javadoc工具.有人可以解释这两种方法的优缺点是什么？它们是互相排斥的吗？是否有Doxygen的Maven插件？