代码文件外的代码文档

Question

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

Answer 1

当文档文本在源代码之外时,Doxygen也可以记录代码.只需创建一个文本为注释的源文件,其中包含标题:

例如,如果你有

SOURCE.H

void func();

你可以加

SOURCE.DOX

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

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

@Laszlo Papp:这不是关于"应该放置评论的地方"的讨论.Stackoverflow更适合Q&A格式. (2认同)
@LaszloPapp：一件事是评论，另一件事是文档。API的文档可以是一本书。在源之间放置这样的内容会使源本身不可读：如果每条代码行相距100行，如何遵循逻辑？本书未与源代码一起编写，而是在源代码成为候选发行版之后，向用户解释如何使用API。这与源代码中写的几个单词完全不同，目的只是为了向源代码阅读器和API开发人员证明其形状和形式。 (2认同)