用沙堡记录外部dll

Question

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

将外部DLL文件添加到文档源确实记录了类,但所有摘要和其他信息都不可用.是否可以记录这些文件(最好不必将程序集反编译/重新创建为项目),因此我可以使用sandcastle生成相关的HTML文档？

我试图保持Sandcastles工作目录的启用,看看.xml文件(我看到的是从我的其他项目中复制过)是以某种方式生成并放在这个目录中.这似乎不是这种情况,没有生成文件,而是直接生成html文件.

Answer 1

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

• 为您可能想要记录或/和的外部 DLL 的所有项目添加“缺失”注释
• 将概念性主题添加到您自己的程序文档中。

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

建议的解决方案（1）：

1. 创建一个如下所示的空白 XML 注释文件，并以程序集名称命名，扩展名为 .xml，例如 PDUNZDLL.xml

   <?xml version="1.0"?>
   <doc>
     <assembly>
       <name>PDUNZDLL</name>
     </assembly>
     <members>
     </members>
   </doc>
   

2. 将此文件保存到例如 Debug 文件夹D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug

3. 双击“项目属性”（参见下面的第二个快照）
4. 在“组件配置”对话框中，将“IntelliSense 组件”添加到项目中。
5. 选择“缺失标签”并根据您的喜好设置项目的“显示缺失标签”属性。这将强制构建为您可能想要记录的所有项目添加“缺失”注释。
6. 构建项目，您将在项目的输出文件夹中找到一个以程序集命名的新 XML 注释文件，例如D:\Visual-Studio-2015\Projects\WindowsApplication2\Documentation1\Help
7. 编辑<member>XML 注释文件中的元素以添加您想要为每个成员添加的注释，如第二个快照中所示。

完成后，将原始占位符文件替换D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug\PDUNZDLL.xml为包含您编辑的注释的构建生成的文件。重建您的文档项目。

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

建议的解决方案（2）：

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

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

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

快乐帮助创作！