Problems with missing members and <exclude> tag

May 29, 2007 at 6:21 PM
I am having problems using the <exclude> tag in classes that inherit from classes that do not have an <exclude> tag on them. I have a base class that has many descendants. I don't yet want to release documentation on every descendant. But, when I add an <exclude> tag on a decendant class, all public and protected members in my base class are no longer included in the help file.
Coordinator
May 29, 2007 at 8:29 PM
As far as I know, <exclude> is working correctly and only excludes the item it appears on. It's not designed or coded to remove any base classes or descendents. If you can come up with a small example that demonstrates the issue, I'll take a look at it.

Eric
May 29, 2007 at 9:43 PM
Thanks for quick reply Eric. I've had a hard time pinning down the exact issue on my big project. So far the only way it works is if I remove all <exclude> tags on classes that inherit from the base class. I'll try and work up a simple example. Do I just email it to you?

Is there anything else I can look at in the Working folder that may provide a clue? Also, when I add the tag to the source I just put a single XML comment line with the exclude tag in it. Using VB.NET it looks like this:

''' <exclude></exclude>

Is this correct?
May 29, 2007 at 10:58 PM
I've made a small sample with only 4 classes in it that reproduces the problem very easily. Let me know how I can get it to you.

Thanks,
John
Coordinator
May 30, 2007 at 2:41 AM
You can create a work item under the Issue Tracker or you can e-mail it to me. My e-mail address is in the About box and in the footer of the pages in the help file. Since exclude is an empty tag, I usually specify it as <exclude/> but it should work the other way. The only other requirement is that it appear at the same level as the <summary> tag (i.e. not nested within it or some other tag).

Eric
May 30, 2007 at 4:38 PM
I uploaded everything to a new Issue in the Issue Tracker. Thanks for the great support!

John
Coordinator
May 30, 2007 at 7:30 PM
I found the problem. When removing a type, it enumerates all members in the type and removes them as well. The problem is that it isn't currently checking to make sure that the member is part of the class so its also removing base class members as well. I'll fix it and it'll be in the next release.

Eric
May 30, 2007 at 9:29 PM
That was quick!

Thanks again,
John
Coordinator
May 31, 2007 at 2:28 AM
I think the next CTP is due in a week or so and the next version of the help file builder will be out shortly after that. If you need the fix sooner, let me know and I can e-mail you the code to fix the problem in the current version. I just had to fix one method.

Eric
May 31, 2007 at 6:45 AM
That would be great Eric. I have a ton of classes that use mutliple levels of inheritance so you may as well email me the patch so I can give the fix a good work-out.
Jun 1, 2007 at 4:50 PM
The patch is working great. All my class documentation is now showing up exactly how I wanted it to. This feature and the <code> tag add-ons really helped me a lot. My documentation looks very professional. Thanks a lot for the great tool and awesome support!
Jun 13, 2007 at 11:05 PM
When do you expect this fix to be released generally? I am having the same issue.
Coordinator
Jun 13, 2007 at 11:43 PM
The next Sandcastle CTP is supposed to be out by the end of the week. Updates to the help file builder usually follow within a week or so of that. If you need the fix sooner, I can e-mail you the section of code to patch in the current version.

Eric
Jun 14, 2007 at 6:43 AM

EWoodruff wrote:
The next Sandcastle CTP is supposed to be out by the end of the week. Updates to the help file builder usually follow within a week or so of that. If you need the fix sooner, I can e-mail you the section of code to patch in the current version.

Eric



Thanks anyway, i'll wait for the update.
Mar 8, 2010 at 5:29 PM

Hello Eric,

I have two methods of the same name with different signitures in the same class. One is marked Obsolete the other is not.

        /// <summary>
        /// Does something.
        /// </summary>
        /// <exclude/>
        [Obsolete("This is a deprecated method.")]
        public virtual double[] MyMethod(int k,Object o)
        {
            ...
        }

current method:

        /// <summary>
        /// Does something.
        /// </summary>
        public virtual double[] MyMethod(Object o)
        {
            ...
        }

Both are being excluded from my documentation. Is this an issue with Sandcastle or SHFB? I'm using SHFB v1.8.0.2.

--brian

Coordinator
Mar 8, 2010 at 7:19 PM

The exclude tag is converted to an entry in the API filter used by MRefBuilder.  The API filter goes by name alone and doesn't differentiate by signature so if one overload is removed, all will be removed.

Eric

 

Mar 8, 2010 at 7:26 PM
Edited Mar 8, 2010 at 7:27 PM

Is this in Sandcastle's MRefBuilder.exe or SHFB's SandcastleBuilder.MRefBuilder.dll?

Are there plans to extend the ability of either to account for signature?

--brian

Coordinator
Mar 9, 2010 at 1:34 AM
Edited Mar 9, 2010 at 1:36 AM

That's Sandcastle's MRefBuilder.exe so it's not under my control.  A plug-in could be written for SHFB to remove items based on the full signature but I have no plans to implement one.  It does have it's shortcomings, but the API filter is more efficient at removing elements since it happens when the info is generated rather than afterwards.

Eric