我目前工作的软件组最近决定开始记录我们的代码库。他们最初采用的方法是使用内置的三斜杠 /// 记录方法。
我们开始发现的一个新问题是，通过 doxygen 运行它的结果是代码库的一个非常好的表示，但供程序员使用，我们原本打算让我们的系统工程师阅读这个文档，他们经常会来我们问一个任务到底在做什么。
有没有一种简单的方法来使用 /// 方法和 doxygen 来记录我们的代码，如果我们以某种方式运行它，我们可以生成一个文档，该文档只包含系统工程版本的文档，而不需要所有额外的绒毛标准程序员文档会吓跑系统人员，例如方法和成员变量等？也欢迎任何替代解决方案建议。
很抱歉，如果这对我们要完成的工作有点混乱，我可以在收到回复时进行调整。谢谢。
我不认为这会让你得到你想要的。听起来您真正想要的是拥有系统工程师可以使用的良好规范文档，以及验证代码是否按照这些规范运行的良好单元测试。内联代码文档确实更适合软件工程师。
您的问题有点令人惊讶和有点害怕的是，软件工程师正在创建一个系统工程师必须使用的系统，并且软件工程师正在从无到有地创建功能。由软件工程师定义功能时，您应该格外小心；他们应该实现指定的功能（并且该规范应该是系统工程师使用的）。
如果您正在编写代码文档，那么您可以假设它会被程序员阅读。可以从输出中去除私有成员，这允许您将公共成员记录为公共文档。如果您没有记录代码，即非开发人员使用的最终用户界面，那么我认为代码不是最好的地方。
您可以做的一件事是使用 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。
在我们的项目中，基本上每个使用该程序的人也都使用它编写代码，因此使用文档与代码交叉链接是很好的。但正如其他人所指出的，它可能不是典型的最终用户文档的最佳解决方案。