Generating Help Documentation for VC++ Project.

Topics: General Questions
Jun 9, 2010 at 2:28 AM

Hi All,

I am working on a VC++ project that generates an ATLCOM dll and this dll is being used by some VC# application. Now I want to create the documentation for all the APIs/Interfaces exposed in the dll. I have already added the xml comments for all the APIs and able to generate XML documentation. I have included the dll in the VC# application and compiled it and then it creates Interop.<name>.dll and I have added this Interop.<name>.dll in the DocProject and able to generate chm help file with it. But the .chm file getting generated is not having the comments I have added in the xml format above source code APIs in dll.

I need help regarding how I can generate the help file which contains all the changes of xml comments added in dll.

thanks,  

Jun 9, 2010 at 3:21 AM

Hi,

Add your XML documentation file to the Help\Comments\ folder in your DocProject or DocSite.  Use the same file name as the assembly but with an .xml extension instead of .dll.

Also ensure that an assembly element is present in the file and that it has the correct value:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Interop.NameWithoutFileExtension</name>
    </assembly>
    ...
</doc>

Actually, I don't remember if the assembly element is a requirement, but it could be :)

- Dave

Jun 9, 2010 at 4:35 AM

Hi Davedev,

I am doing the following steps but still not able to get the effect of xml in the chm file.

1) Downloaded project http://docproject.codeplex.com/
2) Installed , it is using sandcastle to generate help file.
3) Open visual studio and create project of type "Doc Project"  ,Under Visual C#.
4) From program files, opened "Doc Project External UI" , this is there as I installed the Doc Project
5) Selected the project I have created.
6) Open Configuration setting in same UI.
7) Change the Assembly name in xml file to Interop.<file> and Copy the xml documentation in Help\Comments in the DocProject and Add an existing item in Visual Studio editor for DocProject, save it.
8) Set the property "External Sources", Interop.<file>.dll from the VC# application which is using ATLCOM dll, Interop.<file>.xml documentation from Help\Comments.
8) Also clicked on toolbar books icon "Shows topic explorer..." and create a filter for all types.
9) Generated help file.

But still it is generating the chm file only from Interop.<file>.dll source code, the comments added above source code present in Interop.<file>.xml is not taking any effect. Please let me know if I need to configure any specific parameter for this or how it can be achived.

thanks,

Jun 11, 2010 at 10:38 PM

Hi,

4) You can use the DocProject Properties window in Visual Studio instead as long as you're not using an Express edition.  Just right-mouse click your DocProject or DocSite in Solution Explorer and select DocProject Properties.
7) This is not necessary if you're adding the interop assembly to External sources.  Sorry I wasn't clear before.  My previous instructions assumed that you were adding a project reference, but I realize now that it doesn't make sense for an interop assembly :)
8) It seems like you've done this correctly, although you don't have to place the .xml file in the Help\Comments folder.  It can be located in the same place as the interop assembly if you want; i.e., the assembly and its XML documentation file can use the same path in the External sources dialog.  Again, my previous instructions assumed that you weren't using External sources; see my response to #7.
8) [sic] What do you mean by "create a filter for all types"?  Perhaps this is the reason that you're not seeing any documentation?  Make sure that types you haven't excluded actually have corresponding elements in the XML documentation file that you've created.

There are no specific parameters or special configurations required to have Sandcastle include your doc comments.  DocProject simply passes the list of assemblies to Sandcastle and copies the XML documentation files to the temporary build folder so that Sandcastle will find them.

Check the temporary build folder to see if your XML documentation file was copied: buildhelp\assembler\Comments\

If the XML documentation file is there, then it probably has invalid content.  If you'd like to post a snippet or send me the entire XML document file then maybe I could point out where it's invalid.

- Dave