记录一个库——所有的东西还是只是公共头文件中的函数？
如果您正在开发和记录一个库..您是否记录每个源文件中的每个函数/数据结构，或者只是记录公共标头中出现的公共函数/数据结构？
我倾向于第二种选择，这样可以吗？
if you are developing and documenting a library.. do you document every single function / data structure from every source file, or just the public ones that appear on the public header??
im leaning to the second option, is this ok?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
您问题的答案取决于谁将阅读文档。如果文档是提供给 API 用户的，那么最好只向他们提供公共接口的文档。这样，他们就不会被与他们无关的细节所淹没。
另一方面，如果您的文档是由维护库的人员阅读的，那么它应该包括有关公共和私有代码的文档。
现在我对 arne 使用了一种稍微不同的方法。我有一个脚本，它将公共接口所需的头文件复制到一个单独的目录中进行打包。无论如何，这对于生成版本是必要的。该脚本还将 Doxyfile 配置复制到该目录，然后对减少的文件集运行 doxygen。这样我就有了一个 doxygen 配置文件，可以用来生成公共和私人文档。
The answer to your question depends on who is going to read the documentation. If the documentation is going to users of your API, it is probably better that you only provided them with documentation for the public interface. As this way they will not be overwhelmed by details that are not relevant to them.
On the other hand if your documentation is to be read by people maintaining the library, it should include documentation on both the public and private code.
Right now I am using a slightly different approach to arne. I have a script which copies the header files needed for the public interface to a separate directory for packaging up. This is necessary anyway for producing releases. The script also copies the Doxyfile configuration to that directory and then runs doxygen on the reduced set of files. That way I have one doxygen configuration file that I use to produce both public and private documentation.
这取决于您是否想要更改该库中的任何内容，例如五年后。在这种情况下，拥有文档会派上用场。但是，您应该以某种方式将您的“私人”文档与您提供给用户的文档分开。这可以通过使用两个具有不同 INPUT 的单独 doxygen 配置文件来完成。
That depends on whether you ever want to change anything in that library, say, five years from now. In that case, having documentation can come in handy. However, you should somehow separate your "private" documentation from the documentation you provide to users. This can be done by using two separate doxygen configuration files with different INPUTs.