用沙堡记录外部 dll

Question

我目前正在开发一个应用程序，它需要我无法控制的外部 dll。我想为这些类添加文档，以便其他人可以理解为什么我要对这些外部 DLL 文件进行某些调用。

将外部 DLL 文件添加到文档源确实记录了类，但所有摘要和其他信息都不可用。是否可以记录这些文件（最好不必 decompile/recreate 将程序集作为项目），这样我就可以使用 sandcastle 生成相关的 HTML 文档？

我试图保持 Sandcastles 工作目录处于启用状态，以查看 .xml 文件（我看到的是从我的其他项目复制过来的）是否以某种方式生成并放置在该目录中。好像不是这样，没有生成文件，直接生成了html个文件。

Answer 1

据我了解您关于为外部 DLL 用例创建文档的问题，我认为您可以采取两种可能的方式：

为您可能想要记录的外部 DLL 的所有项目添加 "missing" 注释 or/and
将概念主题添加到您自己的程序文档中。

我的示例解决方案 WindowsApplication2 项目有一个使用简单的 PDUNZDLL 添加两个值的表单。添加了 Sandcastle 帮助文件生成器项目 "Documentation1" 和两个文档源（现阶段没有 XML 注释文件，请参见下面的第一个快照）。您知道 - 没有 XML 注释文件的 DLL 会导致缺少红色摘要。

建议解决方案（一）：

创建一个空白的 XML 注释文件，如下所示，并在程序集后以 .xml 扩展名命名它，例如PDUNZDLL.xml
```
<?xml version="1.0"?>
<doc>
  <assembly>
    <name>PDUNZDLL</name>
  </assembly>
  <members>
  </members>
</doc>
```
将此文件保存到例如调试文件夹 D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug
双击 "Project Properties"（见下面的第二个快照）
在“组件配置”对话框中，将 "IntelliSense Component" 添加到项目中。
Select "Missing Tags" 并根据您的喜好设置项目的 Show Missing Tags 属性。这将强制构建为您可能想要记录的所有项目添加 "missing" 注释。
构建项目，您将在项目的输出文件夹中找到一个以程序集命名的新 XML 注释文件，例如D:\Visual-Studio-2015\Projects\WindowsApplication2\Documentation1\Help
编辑 XML 评论文件中的 <member> 元素，为每个成员添加您想要的评论，如第二个快照所示。

完成后，替换原来的占位符文件，例如D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug\PDUNZDLL.xml 使用您编辑的评论从构建中生成的那个。重建您的文档项目。

这当然很耗时，因为任何帮助编写应用程序。而这实际上是 DLL 开发人员的任务。

建议方案（二）：

读懂您的字里行间“...以便其他人可以理解我为什么要对这些外部 DLL 文件进行某些调用。”引导我向您自己的程序添加补充文档的建议。

所以，我的意思是添加描述如何调用外部 DLL 文件的功能的概念主题。

我删除了"Documentation Sources"下的DLL，添加了一个新文件夹 "ExternalDLL"，添加了一个新项目概念和演练，在解决方案资源管理器中双击 ContentLayout.content，并完成内容布局的所有步骤，重建文档项目，生成如下面第三个快照所示的帮助文件（也请参阅背景信息）。

祝创作愉快！

用沙堡记录外部 dll

Documenting external dll's with sandcastle

c#

sandcastle

xml-documentation