用沙堡记录外部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. 编辑XML注释文件中的<member>元素，以便为每个成员添加所需的注释，如第二个快照中所示。

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

这对于编写应用程序的任何帮助来说当然都很耗时。它实际上是DLL开发人员的任务。



建议的解决方案（2）：

在你的行之间阅读“...以便其他人可以理解为什么我正在对这些外部DLL文件进行某些调用。”引导我建议在你自己的程序中添加补充文档。

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

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



快乐帮助创作！