代码文档放在哪里？

我目前正在使用两个系统编写代码文档（上午使用C ++）：

• 使用Doxygen格式在代码旁边添加有关方法和类成员的文档。在服务器上，Doxygen在源上运行，因此可以在Web浏览器中看到输出
• 概述页面（描述一组类，应用程序的结构，示例代码等）被添加到Wiki中。

我个人认为这种方法很简单，因为有关成员和类的文档确实与代码接近，而概述页面确实很容易在Wiki中进行编辑（并且还很容易添加图像，表格等）。Web浏览器允许您查看两个文档。

我的同事现在建议将所有内容都放入Doxygen，因为我们可以创建一个包含所有内容的大帮助文件（使用Microsoft的HTML WorkShop或Qt Assistant）。我担心的是，编辑Doxygen样式的文档要困难得多（与Wiki相比），尤其是当您想要添加表，图像等时（或者Doxygen的“预览”工具不需要您生成）代码才能看到结果？）

大型开源（或封闭源）项目使用什么来编写其代码文档？他们还将Doxygen样式和Wiki分开吗？还是他们使用其他系统？

公开文档的最合适方法是什么？通过Web服务器/浏览器，还是通过大的（几个100MB）帮助文件？

在编写代码文档时，您采用哪种方法？

将所有文档都放在一个系统而不是两个系统中是一个真正的优势。诸如备份与还原，版本控制，全局搜索，全局搜索与替换，交叉链接之类的操作，以及如您所写的将所有文档放入一个最终文档中的操作，通常都可以减少不必要的“摩擦”，而不必维护两个不同的文档。系统具有重叠的功能。

另一方面，您必须考虑这些优势是否超过了Wiki的易用性。使用Wiki可以更快地进行“编辑/生成/优化编辑/生成”圈子。我猜想，使用doxygen可以使您的概述页面作为一个单独的doxygen子项目保持相当快的周期。您可以利用doxygen 的外部链接功能，这当然不能替代“快速预览”，但可以朝着这个方向迈出一步。到目前为止，我还没有自己做过，但是我想如果您想知道它是否适合您，就必须自己尝试一下。

关于其他项目：我认为像doxygen这样的工具主要用于图书馆文档编制。如果您不是第三方库供应商，并且使用库的每个人都可以完全访问源代码，那么对诸如doxygen之类的工具的需求就值得怀疑。例如，在我们的团队中，除了最终用户文档和数据库模型文档外，几乎没有代码外的外部文档。我们用于此类文档的主要工具是 docbook和fop，这使我们获得令人满意的结果。

首先使用代码文档。如果可能，添加Wiki和其他方法

我知道，要维持它将会很困难。

实用答案：

实际上，开发人员要做的第一件事就是检查代码。

作为开发人员，我喜欢拥有外部文档，例如Wiki，手册。但是，我要做的第一件事是检查代码（有时来自其他开发人员，有时是我自己的）。

作为一个在多个项目和客户中工作过的开发人员，我会尽力添加外部文档，但是，这样做通常会带来很多工作量，并且无法支持Wiki。

有时，项目经理和其他老板不关心文档，而其他开发人员则不关心文档。

而且，我所能做的就是在代码中添加一些注释。

祝好运

有些使用其他系统- 例如以Python的Sphinx为例，它们拥有一个构建所有内容的多合一文档系统（它也适用于C / C ++）

我一直认为文档与代码是分开的，doxygen很棒，但这只是对API的概述，而不是“文档”。为此，Wiki非常棒，但是我更喜欢使用ASCIIDOC并将其结果与代码一起存储在源代码控制中，主要是因为我可以从中生成PDF并交给其他人（例如测试人员，客户等）。

Doxygen允许您构建PDF，HTML，Wiki页面，几乎可以想到的所有内容。

我个人的喜好是同时拥有Doxygen和Wiki以及脚本或其他东西时要检查的东西。

从1.8.0版开始，doxygen 支持Markdown，这将使编写静态页面的体验与在Wiki系统中一样方便。

目标观众

我认为在回答这个问题时，您确实需要询问谁打算阅读本文档。开发人员与用户甚至业务分析师的需求完全不同。

• 作为开发人员：与正在研究的代码相关的文档，接口合同等详细信息以及用法示例。也许是一些高级文档，以及很好的协议规范。
• 作为用户：可通过帮助菜单或可访问的网站获取有关如何使用该软件的文档。
• 作为业务分析人员：以文档或可访问网站的形式提供的文档很有用。关于协议，高级体系结构和用例的少量详细信息是最好的。

保养

至于该文档的来源放置位置将取决于您的受众，以及谁在为您的受众写作。

• 只有一所开发商吗？将所有内容放入代码中。它将鼓励它进行更新。您将需要一种鼓励文件更新与代码更改同样重要的文化。
• 有一家开发人员和文档编写者吗？划分职责。为开发人员使用面向开发人员的工具，为文档编写人员使用文档编写人员工具。

尽可能确保可以执行代码示例或用例。自动执行它们并在内部标记故障。这些页面很可能是不良或不良的文档。

另外，无论您选择使用哪种工具编写文档，都需要一种可靠的方法来将文档的特定版本与特定版本的代码相关联。即使在只有一个常绿部署的快乐云土地上，这仍然是有益的。

整合文件

可能需要集成才能生成一些文档，但是请注意，只有用户希望在一个地方可以访问他们需要的所有文档。

业务分析师对API规范，设计规范和使用方案位于单独的文档或网站的不同部分中感到非常满意。

开发人员更喜欢从源头可见的所有内容，但是很高兴在代码外部有几个高级设计文档和详细的协议规范文档，尽管最好在同一签出之内。

你的情况

老实说，您的Wiki中的文档可能与您的代码库中的文档类型不同。合并也可能没有意义。

另一方面，可以通过几种简单的方式将两者整合在一起。

• 源文档工具（例如doxygen）可以生成html，而wiki则位于网络服务器上。这是一个简单的集成点，只需将构建版本与Wiki一起提供并相互链接两者即可。
• 某些Wiki产品将允许您直接从可检入代码库的文件中运行Wiki。这提供了一个简单的所见即所得工具，同时使文档与代码配对。
• 也可以使用其他格式，例如pdf，但这取决于您要使用的特定工具。将您的Wiki刮入markdown文件并通过doxygen（或其他工具）进行输入可能是有意义的。分别对Wiki和源进行pdf并使用pdf合并工具可能会有意义。

归根结底，找出哪种文档系统维护成本低，并帮助您交付高质量的产品，如开发人员，业务分析师和用户的观众所看到的。任何阻碍这些群体的事情都必然会降低产品质量。

如果使用的是ASCII，则应将隐藏的文档数据存储在源代码的高位！然后，只有最聪明的用户（应读：当之无愧）才有机会使用您的文档。

具有定义明确，易于导出，可移植格式的文档可能是真正的优势。如果狮身人面像死了（不太可能），我将转换为其他系统，我想这将是一个可编写脚本的任务。将数据移出Wiki（可能以专有格式存储在数据库中可能会很麻烦）。