C#为非程序员生成源代码文档
我目前工作的软件组最近决定开始记录我们的代码库。他们最初采用的方法是使用内置的三斜杠///方法进行记录 我们开始发现的一个新问题是，通过doxygen运行该文件的结果是代码库的一个非常好的表示形式，但对于程序员来说，这是一个非常好的表示形式，我们希望系统工程师能够阅读该文件，他们经常来问我们任务到底在做什么 有没有一种简单的方法可以使用///方法和doxygen记录我们的代码，如果我们以某种方式运行它，我们可以生成一个只包含文档的系统工程版本的文档，而不需要标准程序员文档的所有额外绒毛，这些绒毛会吓跑系统人员，比如方法和成员变量等。？也欢迎提出任何替代解决方案建议 我很抱歉，如果这是一个有点困惑，因为我们正在努力完成，我可以调整作为回应进来。C#为非程序员生成源代码文档,c#,doxygen,documentation-generation,C#,Doxygen,Documentation Generation,我目前工作的软件组最近决定开始记录我们的代码库。他们最初采用的方法是使用内置的三斜杠///方法进行记录 我们开始发现的一个新问题是，通过doxygen运行该文件的结果是代码库的一个非常好的表示形式，但对于程序员来说，这是一个非常好的表示形式，我们希望系统工程师能够阅读该文件，他们经常来问我们任务到底在做什么 有没有一种简单的方法可以使用///方法和doxygen记录我们的代码，如果我们以某种方式运行它，我们可以生成一个只包含文档的系统工程版本的文档，而不需要标准程序员文档的所有额外绒毛，这些绒毛
谢谢。我认为这不会满足你的需要。听起来，您真正想要的是系统工程师可以使用的良好规范文档，以及验证代码是否按照这些规范运行的良好单元测试。内联代码文档对软件工程师来说更重要
关于你的问题，有点让人惊讶和有点害怕的是，软件工程师正在创建一个系统工程师将不得不使用的系统，而软件工程师正在从无到有地创建功能。您应该非常小心地让软件工程师定义功能；它们应该实现指定的功能（并且该规范应该是系统工程师所使用的）。如果您正在记录代码，那么您可以假设程序员将阅读它。可以从输出中剥离私有成员，这允许您将公共成员作为公共文档进行文档记录。如果您没有记录代码，即非开发人员使用的最终用户界面，那么我认为代码不是它的最佳位置。您可以做的一件事是使用doxygen的
\pagedocsrc/*!
\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在我们的项目中，基本上每个使用该程序的人都会使用该程序进行编码，因此将使用说明文档与代码交叉链接是很好的。但是正如其他人指出的，它可能不是典型的最终用户文档的最佳解决方案。我们以系统工程可理解的方式记录代码，以便他们知道我们的实现是什么。原来的设计是由系统工程师完成的，几年前在C++中由软件工程师完成。最近，我们开始将代码库转换为C#，在此期间，我们做了一些小的调整，并且有许多新的（er）系统工程师在使用该软件的不同产品线。这就使得他们需要问，从最初的设计到各种变更请求，今天的代码到底做了什么。