doxygen - 记录一个库 - 一切或只是公共头文件中的功能？

Question

如果您正在开发和记录一个库..您是记录每个源文件中的每个函数/数据结构，还是只记录公共头文件中出现的公共文件？

我倾向于第二个选项，这样可以吗？

Answer 1

您的问题的答案取决于谁将阅读文档。如果文档要发给 API 的用户，最好只向他们提供公共接口的文档。这样他们就不会被与他们无关的细节所淹没。

另一方面，如果您的文档要由维护库的人员阅读，则它应该包括有关公共代码和私有代码的文档。

现在我正在使用一种稍微不同的方法来处理 arne。我有一个脚本，它将公​​共接口所需的头文件复制到单独的目录以进行打包。无论如何，这对于制作发行版都是必要的。该脚本还将 Doxyfile 配置复制到该目录，然后在减少的文件集上运行 doxygen。这样我就有了一个 doxygen 配置文件，用于生成公共和私人文档。

Answer 2

这取决于您是否想要更改该库中的任何内容，例如，五年后。在这种情况下，拥有文档会派上用场。但是，您应该以某种方式将您的“私人”文档与您提供给用户的文档分开。这可以通过使用具有不同 INPUT 的两个单独的 doxygen 配置文件来完成。