代码文件外的代码文档答案

【问题标题】：Code documentation outside code file代码文件外的代码文档
【发布时间】：2013-08-17 16:31:51
【问题描述】：

出于某些原因，我想记录一个 API，但我不想直接在源代码中编写文档，因为它现在已被广泛使用。我正在寻找一个文档生成器工具，它可以将文档文件作为输入，并且能够从源代码中获取函数原型并检查与文档的一致性。你知道有什么工具可以做到这一点吗？

【问题讨论】：

代码是用什么语言编写的？这可能非常相关。你应该用它标记你的问题。
现在是 c++。无论如何，我也很想有一个更笼统的答案，因为我可能也需要这种用于其他语言的工具。
文档“远离”源文件在更新源时往往不太可能更新（并且考虑到您发现代码和 cmets 不同步的频率）在同一个文件中），我会说这不是一个好计划。
反正有很多同步问题。我不认为这是与“文档所在位置”相关的问题。如果您想分发一个库，请花费所有时间来保持 API 文档的一致性。请注意，我说的是记录 API，而不是内部库。
您应该使用 doxygen 文档进入标题，而不是源文件。你觉得可以吗？

【解决方案1】：

Doxygen 也可以在文档文本位于其源代码之外时记录代码。只需创建一个文本为注释的源文件，包含标题：

例如，如果你有

SOURCE.H

void func();

你可以添加

SOURCE.DOX

/**
   \function void func()
   Your usual doxygen text here.
*/

并生成使 doxygen 接受 .h 和 .dox 文件的文档。

【讨论】：

我同意前面的cmets，不把它写进源代码是个坏主意。我认为我们应该说服作者改变他的心态。 :)
@Laszlo Papp：这不是关于“cmets 应该放在哪里”的讨论。 Stackoverflow 更适合问答形式。
@Emilio Garavaglia：谢谢你的回答。
@LaszloPapp：一件事是 cmets，另一件事是文档。 API 的文档可以是一整本书。将这样的内容放在源代码之间会使源代码本身不可读：如果每个代码行相距 100 行，我该如何遵循逻辑？这本书不是用源代码写的，而是在源代码成为候选发布后，向用户解释如何使用 API。它的目的和业务与在源代码中编写的几个字完全不同，只是为了向源代码阅读器和 API 开发人员证明其形式和形式。
我在玩 Doxygen。它似乎受到任何为从源代码生成文档而构建的系统的缺点。例如，没有方便的方法来记录一组重载函数stackoverflow.com/questions/11860660/…你对此有什么见解吗？