Exclude Tag for COM Interfaces?

Apr 1, 2008 at 5:43 PM
I try to document a class library project with a ComClass and ProgId decorated class. The compiler generates the COM interfaces in the background, which I don´t want to be included in my documentation.

So I generated a comment XML file with the following content:

<?xml version="1.0"?>
<doc>
<assembly>
<name>MyAssembly</name>
</assembly>
<members>
<member name="T:MyNamespace.MyCOMClass.__MyCOMClass">
<exclude />
</member>
</members>
</doc>

This worked in prior versions of SHFB. If I replace the exclude tag with a summary tag, everything works ok. So I am sure that no typo is in my xml file.

I guess the . in the member name is the problem. But as said it worked in older versions of SHFB.
Coordinator
Apr 1, 2008 at 6:18 PM
Try using the ApiFilter property. It will let you exclude classes that you can't comment.

Eric
Apr 1, 2008 at 6:39 PM
Thanks for the fast reply.

I clicked on the ApiFilter property and it showed the two automatically generated interfaces as unchecked. Checking was impossible. There appeared a message saying there is an exclude tag hiding it. So SHFB recognizes my tags.

I removed my xml comment file from the project, reopened the ApiFilter property. Now the two interfaces were checked and I could uncheck them.

I still think it is a bug in the software, but as I got my desired result it doesn´t really matter ;)
Coordinator
Apr 1, 2008 at 10:22 PM
If you can send me an example that demonstrates the problem with the <exclude/> tag not working, I'll check it out. My e-mail address is in the About box and in the footer of the pages in the help file.

Eric
Apr 24, 2008 at 10:01 PM
Edited Apr 24, 2008 at 10:16 PM
Any chance there was a resolution to this? I am hitting the same problem. For example,

<member name="T:DiscoveryLogic.ScienceWireServices.DataObjects.NIHProject.LookupDS.ApplIDsDataTable">
<summary>33</summary>
<remarks>34</remarks>
</member>
<member name="M:DiscoveryLogic.ScienceWireServices.DataObjects.NIHProject.LookupDS.ApplIDsDataTable.Clone">
<exclude />
</member>

The summary and remarks show up, but the Clone method is not excluded. If I changed the <exclude /> to a <summary>ABC</summary>, the Clone method shows the summary text.

This exclude however works:
<member name="M:DiscoveryLogic.ScienceWireServices.DataObjects.DataSets.OTTTechnologyDS.OTTTechnologyDataTable.Clone">
<exclude />
</member>

Additionally, if I go into the APIFilter, it shows the method as excluded ("Removed via an <exclude /> tag").

The classes are from the same assembly, but the excludes are in two different files that are added as "comments-only" files.
Coordinator
Apr 25, 2008 at 1:33 AM
The problem was with nested classes marked with an <exclude/> tag not being removed. It has been fixed and will be in the next release. However, in the OP's case the ApiFilter was a better choice as it removed the need to maintain a separate XML comments file. I'd suggest doing the same in this case too.

Eric
Apr 25, 2008 at 1:17 PM
Eric,

Thank you for the quick reply.

I tried the 1.6.0.6 beta this morning and the problem still existed. Was the fix supposed to have already been in that?

I could use the APIFilter, and doing so works. However I prefer use of the exclude tags. I have written a utility that reads XSD (dataset) files, allows the user to comment the classes, methods, and properties that are unique to the dataset, and then create an external comments-only XML file. The utility, and here's the advantage of excludes over APIFilter for us, also automatically generates exclude tags for those elements that we don't want to include in the documentation. With the quantity of datasets we're documenting, the quantity of excludes for each, and the rate at which we are defining new datasets, the auto-generated excludes by the utility are preferred over the manual use of APIFilter.

Greg
Coordinator
Apr 25, 2008 at 2:49 PM
No, the fix isn't in 1.6.0.6. It'll be in the next release (1.7.0.0) which is due out within a week of the next release of Sandcastle. The next Sandcastle release should be out late next week based on the latest post in the Sandcastle blog.

Eric
Apr 25, 2008 at 3:55 PM
Excellent. I can easily wait until then.

I will post results after it is released.

Thank you.