3

我从事一个使用非托管可视化 C++ 和少量 C# 的项目。我们正在尝试想出一种方法来记录我们的项目，包括 API 参考以及一些额外的概念文档。理想情况下，所有文档都放在一个 .chm 文件中，我们可以将其与我们的产品一起分发。

作为一名长期的 C++ 开发人员，我已经熟悉 Doxygen。有人建议我也研究一下 Sandcastle，但我遇到了一些障碍。

从许多其他来源，包括本网站上的其他帖子，众所周知，sandcastle 不支持非托管 C++。我确实找到了一篇似乎表明您仍然可以通过将 API 参考添加为概念主题来将 C++ 文档塞进沙堡的帖子。

使用 Visual Studio 2010，您可以在非托管 C++ 项目的项目设置中打开 /doc 选项。这会生成 .XDC 文件，然后 Studio 会将其编译为与您的 lib/dll/exe 一起使用的 .xml 文件。我被卡住的地方是不清楚你可以用这个 xml 文件做什么。我在网上找到的一些页面建议您可以将此文件用于智能感知，但我从未见过在非托管 C++ 中使用该文件。我希望我能够以某种方式在 Sandcastle Help File Builder 中使用这个 .xml 文件，但是我找不到任何关于如何在线完成的示例，而且我对 SHFB 所做的每一次尝试都失败了。如果我想添加现有的概念帮助文件，它似乎只需要 MAML 或 HTML 文件。

所以我的问题：

  1. 有没有办法让我的 /doc 生成的 .xml 文件进入我的 SHFB 帮助解决方案？
  2. 如果不是，非托管 C++ 的 /doc 选项有什么意义？
  3. 是否可以对我的 /doc 生成的 .xml 文件进行某种转换以生成 HTML 或 MAML，然后我可以通过 SHFB 导入这些文件？

这可以工作，还是我应该回到 Doxygen？

4

2 回答 2

4

理论上，Sandcastle 可用于记录非托管代码，但它需要一个工具来生成当前由 MRefBuilder.exe 工具为托管代码程序集生成的等效反射数据文件。到目前为止，据我所知，没有人这样做过。

由于我不再使用它，因此我无法评论未管理的 C++ 缺乏 IntelliSense。猜测一下，假设使用相同的编译器但带有一些额外的命令行选项，/doc 可能用于托管代码输出。

使用 XSL 将 XML 注释转换为 MAML 是一种可能，但同样，我不知道有人在追求这种选择。我的猜测是，在这种情况下，大多数人选择使用 Doxygen，因为它是一个成熟的解决方案。

埃里克

于 2013-01-04T02:54:32.140 回答
2

我也有类似的情况。我的 C++/CLI 绑定中需要 XML 文档，以便 .NET 代码可以通过 Intellisense 看到它们。但仅供参考，Visual Studio 2010 不支持原生代码中的 XML 文档：

https://msdn.microsoft.com/en-us/library/ms177226(v=vs.100).aspx

Visual Studio 2010
在 Visual C++ 中，您可以将 XML 文档（三斜杠）注释添加到源代码并指示编译器将它们输出到 .xml 文件。然后可以将该文件输入到为代码中的类创建文档的过程中。此版本的 Visual C++ IDE 不支持 Intellisense 中的 XML 注释。

Visual Studio 2013 中删除了该限制。但是，如果您在本机代码中使用模板（例如 Boost 库），它仍然是一个令人讨厌的生态系统：

在当前版本中，不会对模板或包含模板类型的任何内容（例如，将参数作为模板的函数）处理代码注释。添加此类注释将导致未定义的行为。

I found your question while searching for a way to temporarily disable the XML comment parser with a #pragma or #define when including such libraries.

于 2017-03-03T15:38:12.853 回答