Sandcastle、/doc 和非托管 C++答案

【问题标题】：Sandcastle, /doc, and Unmanaged C++Sandcastle、/doc 和非托管 C++
【发布时间】：2012-12-17 03:36:53
【问题描述】：

我从事一个使用非托管可视化 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 文件。

所以我的问题：

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

这行得通，还是我应该回到 Doxygen？

【问题讨论】：

标签： visual-c++ doxygen unmanaged sandcastle shfb

【解决方案1】：

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

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

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

埃里克

【讨论】：

【解决方案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 文档（三斜杠）cmets 到您的源代码并指示编译器将它们输出到 .xml 文件。然后这个文件可以为您的类创建文档的过程的输入代码。 此版本的 Visual C++ IDE 不支持 XML Intellisense 中的 cmets。

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

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

我在寻找一种在包含此类库时使用#pragma 或#define 暂时禁用 XML 注释解析器的方法时发现了您的问题。

【讨论】：