Documenting external dll's with sandcastle

Question

I'm currently developing an application, which requires external dll's which I do not control. I'd like to add documentation for these classes, so that others can understand why I'm making certain calls I'm making to these external DLL files.

Adding the external DLL files to the documentation sources does indeed log the classes, but all the summaries and other information is unavailable. Is it possible to document these files (Preferably without having to decompile/recreate the assembly as a project), so I can generate the related HTML documentation with sandcastle?

I've tried to keep Sandcastles working directory enabled, to see if the .xml files (That I see were copied over from my other projects) were somehow generated and placed in this directory. This doesn't seem to be the case, no files were generated, and it goes straight to generating the html files.

Answer 1

As far as I understand your question about creating documentation for an external DLL use case I see two possible ways that you can go:

• Add "missing" notes for all items of the external DLL that you might want to document or/and
• add conceptual topics to your own program documentation.

My sample solution WindowsApplication2 project has a form to add two values using a simple PDUNZDLL. A Sandcastle help file builder project "Documentation1" was added and two Documentation Sources (at this stage without XML comment file, see first snapshot below). You know - a DLL without XML comments file is resulting in a red missing summary.

Proposed solution (1):

1. Create a blank XML comments file like the following and name it after the assembly with a .xml extension e.g. PDUNZDLL.xml

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

2. Save this file to the e.g Debug folder D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug

3. Double-click the "Project Properties" (see second snapshot below)
4. In the Component Configurations dialog, add the "IntelliSense Component" to the project.
5. Select "Missing Tags" and set the project's Show Missing Tags properties to your liking. This will force the build to add "missing" notes for all items that you might want to document.
6. Build the project and you will find a new XML comments file named after the assembly in the project's output folder e.g. D:\Visual-Studio-2015\Projects\WindowsApplication2\Documentation1\Help
7. Edit the <member> elements in the XML comments file to add the comments that you want for each member as shown in the second snapshot.

When you are done, replace your original placeholder file e.g. D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug\PDUNZDLL.xml with the one generated from the build with your edited comments. ReBuild your documentation project.

This is of course time consuming as any help authoring for applications. And it was actually the task of the DLL developer.

Proposed solution (2):

Reading between your lines "... so that others can understand why I'm making certain calls I'm making to these external DLL files." leads me to the suggestion to add a supplementary documentation to your own program.

So, what I mean is to add conceptual topics describing how you call the features of the external DLL files.

I removed the the DLL under "Documentation Sources", added a new folder "ExternalDLL", added a new item Conceptual and Walkthrough, double-click ContentLayout.content in Solution explorer, and did all the steps for content layout, ReBuild the documentation project resulting in a help file like shown in the third snapshot below (see background info too).

Happy help authoring!