面向非程序员的C#源代码内文档生成

Question

我目前所在的软件团队最近决定开始记录我们的代码库。他们最初采取的方法是使用内置的三重斜杠/文档化方法。

我们开始发现的一个较新的问题是，通过doxygen运行它的结果是代码库的一个非常好的表示，但对于程序员来说，我们原本打算让我们的系统工程师能够阅读这个文档，他们经常会来问我们一个任务到底在做什么。

有没有一种简单的方式来使用/方法和doxygen来记录我们的代码，如果我们以某种方式运行它，我们可以生成一个只包含系统工程版本文档的文档，而不需要标准程序员文档中所有会吓跑系统人员的额外毛绒，比如方法和成员变量等。任何替代解决方案建议也是受欢迎的。

我很抱歉，如果这对我们试图实现的目标有点困惑，我可以根据反馈进行调整。谢谢。

Answer 1

您可以做的一件事是使用doxygen的\page命令，该命令将显示“相关页面”。创建一个文本文件，其扩展名由doxygen处理，然后在其中添加注释。(我使用的是.doc，但您可能希望将其更改为其他名称，以避免与Word文档混淆。我还将这些文件放在一个名为docsrc的公共目录中，以便将它们放在一个位置。)然后，这些页面显示在文档中的单独部分中。

/*!      
\page foobar Foobar calculation

I am using the procedure outlined in the bla bla note to estimate
the foobar in our baz. Lorem ipsum dolor...

\section step1 1. Estimation of the foobar-efficiency of the baz system.

\author jdm
*/

然后，您可以使用\ref foobar或\ref step1创建指向页面或部分的链接。

在我们的项目中，基本上每个使用程序的人都会使用它进行编码，所以使用文档与代码交叉链接是很好的。但正如其他人指出的那样，对于典型的最终用户文档来说，这可能不是最好的解决方案。

Answer 2

我不认为这会给你带来你想要的。听起来您真正想要的是系统工程师可以使用的良好的规范文档，以及验证代码是否按照这些规范运行的良好的单元测试。对于软件工程师来说，内联代码文档确实更重要。

关于你的问题，令人有点惊讶和恐惧的是，软件工程师正在创建系统工程师必须使用的系统，而软件工程师正在从无到有地创建功能。您应该非常小心地让功能由您的软件工程师定义；他们应该实现指定的功能(并且该规范应该是系统工程师所使用的)。

Answer 3

如果你在记录代码，那么你可以假设它是由程序员阅读的。可以从输出中剥离私有成员，这允许您将公共成员记录为公共文档。如果你没有记录代码，即非开发人员使用的最终用户界面，那么我认为代码不是最好的地方。