c# - 使用 sandcaSTLe 记录外部 dll

Question

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

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

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

Answer 1

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

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

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

建议的解决方案(一):

1. 像下面这样创建一个空白的 XML 注释文件，并以带有 .xml 扩展名的程序集命名它，例如PDUNZDLL.xml

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

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

3. 双击“项目属性”(见下面的第二个快照)
4. 在“组件配置”对话框中，将“IntelliSense 组件”添加到项目中。
5. 选择“Missing Tags”并根据您的喜好设置项目的“Show Missing Tags”属性。这将强制构建为您可能想要记录的所有项目添加“缺失”注释。
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 开发人员的任务。

建议的解决方案(二):

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

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

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

祝您创作愉快!