Documenting external dlls with sandcastle

Question

I am currently developing an application that requires an external dll that I do not control. I would like to add documentation for these classes so that others can understand why I make certain calls that I make for these external DLL files.

Adding external DLL files to documentation sources does register classes, but all summaries and other information are not available. Is it possible to document these files (preferably without having to decompile / recreate the assembly as a project), so I can generate the appropriate HTML documentation using sandcastle?

I tried to include the Sandcastles working directory to see if the .xml (which I see were copied from my other projects) were somehow generated and placed in this directory. This is not like the files were not generated, and this is directly related to the creation of html files.

Answer 1

As far as I understand your question about creating documentation for external use of the DLL, I see two possible ways you can go:

• Add “missing” notes for all elements of the external DLL that you can document or
• Add conceptual themes to your own program documentation.

In my test solution, the WindowsApplication2 project has the form for adding two values ​​using a simple PDUNZDLL. The Sandcastle Builder project "Documentation1" and two documentation sources were added (at this point, without an XML comment file, see the first screenshot below). You know, a DLL without an XML comment file leads to a red missing summary.

Proposed Solution (1):

• Create an empty XML comment file as follows and name it after assembly with the extension .xml, for example. PDUNZDLL.xml

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

• Save this file to the Debug folder D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug

• Double-click "Project Properties" (see second screenshot below)
• In the Component Configurations dialog box, add the IntelliSense component to the project.
• Select Missing Tags and set the Show Missing Tags property to your liking. This will force the assembly to add “missing” notes for all the elements you want to document.
• Create a project and you will find a new XML comment file named after the assembly in the project output folder, for example. D:\Visual-Studio-2015\Projects\WindowsApplication2\Documentation1\Help
• Edit the <member> elements in the XML comment file to add comments to each member, as shown in the second snapshot.

When you're done, replace the original placeholder file, for example. D:\Visual-Studio-2015\Projects\WindowsApplication2\WindowsApplication2\bin\Debug\PDUNZDLL.xml with the one that was created from the assembly with your edited comments. Reinstall the draft documentation.

This, of course, takes a lot of time, like any help in building applications. And actually it was the task of a DLL developer.

Proposed Solution (2):

Reading between your lines "... so that others can understand why I make certain calls that I make for these external DLL files." leads me to the proposal to add additional documentation to my own program.

So, I mean adding conceptual topics that describe what you call the functions of external DLL files.

I deleted the DLL in the "Sources of documentation" section, added a new folder "ExternalDLL", added a new item "Conceptual and walkthrough", double-click ContentLayout.content in Solution explorer, and completed all the steps to compose the content, ReBuild documentation project. resulting in a help file as shown in the third snapshot below (see also help information).

Congratulations on your help!