我目前工作的软件组最近决定开始记录我们的代码库。他们一直采用的初始方法是使用内置的三重斜杠///记录方法。
我们开始发现的一个新问题是，通过doxygen运行此结果是代码库的一个非常好的表示，但对于程序员来说，我们希望我们的系统工程师可以读取这些文档。经常来找我们询问一项任务究竟在做什么。
有没有一种简单的方法可以使用///方法和doxygen来记录我们的代码，如果我们以某种方式运行它，我们可以生成一个文档，它必须包含系统工程版本的文档而不需要额外的标准程序员文档的漏洞会吓跑系统人员，如方法和成员变量等？我们也欢迎任何其他解决方案建议。
如果对于我们想要完成的事情有点困惑，我很抱歉，我可以根据回复进行调整。 谢谢。
答案 0 :(得分：1)
我认为这不会让你得到你想要的东西。听起来你真正想要的是拥有系统工程师可以使用的良好规范文档，以及验证代码根据这些规范运行的良好单元测试。内联代码文档更适合软件工程师。
对于您的问题有点令人惊讶和有点可怕的是，软件工程师正在创建一个系统工程师必须使用的系统，并且软件工程师正在从无创建功能。您应该极其谨慎地使用软件工程师定义功能;它们应该实现指定的功能（该规范应该是系统工程师使用的规范）。
答案 1 :(得分：1)
如果您正在记录代码，那么您可以假设它将由程序员阅读。可以从输出中删除私有成员，这允许您将 public 成员记录为公共文档。如果您没有记录代码，即非开发人员使用的最终用户界面，那么我认为代码不是最适合它的地方。
答案 2 :(得分：0)
您可以做的一件事是使用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创建指向该网页或部分的链接。
在我们的项目中，基本上每个使用该程序的人都会对其进行编码，因此将使用文档与代码交叉链接会很不错。但正如其他人指出的那样，它可能不是典型的最终用户文档的最佳解决方案。