Protected method of sealed classes appear in the Index

Try generating documentation for the following code:

using System;
using System.Collections.Generic;
using System.Text;
namespace SandCastleTest
{
public class BaseTest
{
protected virtual void Help()
{
}
}
public sealed class Test : BaseTest
{
protected override void Help()
{
}
}
}

Generate documentation for it using the Sandcastle Aug CTP (HtmlHelp1x). If you'll look at the Contents-tab of the compiled help-file you'll notice that the Help-method is only shown as a method of the BaseTest-class. It correctly doesn't appear as a child of the Test-class as this class is sealed.
If you then click on Test Class in the Contents-tab, you'll get a list of all the members of this class. There also, the Help-method is not displayed. So far so good.
However, if you now switch to the Index-tab you'll notice that the Help-method of the Test-class is incorrectly listed there.

So basically the problem is that the Index-tab incorrectly shows protected methods of sealed class.

Answer this question

Protected method of sealed classes appear in the Index

Hemant Kumar
Hi,

It appears that the Sandcastle Help File Builder v1.3.1.1 now contains an option to hide protected members of sealed classes. I've tested it and it appears to work just fine. Great work!

Michael
Evan Hennis

Thanks Michael and I will investigate this and will provide a fix.

Anand..
Carl Tribble
This is by design and will be the case going forward from now on. Many documentation groups inside Microsoft were not happy with the convention that protected members of sealed classes were "hidden". The argument was that it was important that users of a sealed class the overrides an inherited method should know about the override. Also, some customers were confused that methods would "disappear" as they navigated down the class hierarchy.
JIM.H.
I don't really understand what you're saying in "The argument was that it was important that users of a sealed class the overrides an inherited method should know about the override.". A protected member of class is a member that is only to be used by derived classes. If a class is sealed, than I can't derive from it, but nonetheless my documentation lists a whole bunch of members that I can't possibly ever use. In the case of the API that I am designing right now, this means that more than half of the methods listed in the documentation of a class are completely useless to users of this class. This is extremely confusing and reduces the value of our documentation enormously.

Also, I strongly disagree with your statement that "some customers were confused that methods would "disappear" as they navigated down the class hierarchy". In my mind, if people get confused by this, it's not because of a problem with the documentation but because they're not educated enough in object oriented programming. Second, both classes are intended for completely different audiences; therefore they can have different members. A non-sealed base-class is meant for a developer wanting to extend the capabilities of a class and thus needs more access to the internals of the class. A sealed class is meant for a developer wanting to use a class and therefore does not need to know about the internals.

I would like to ask you to please make this optional behavior because the value of my documentation created using the September CTP has descreased tremendously compared to the documentation created using the August CTP. I can count on a huge number of support requests of people wanting to use a method that they saw in the documentation, but that they apparently can't see using IntelliSense. This is much much more confusing in my mind.

Regards,

Michael
Evan Mulawski
Hi Michael,

Thanks for responding. Yes, I do see your perspective. We have added the transform I mentioned earlier to our feature request list, although I'm afraid I can't give any guarantees about when it will get done.

David
RonanH
I'm not sure if this was supposed to have been fixed in the September CTP (don't really see it in the What's New), but just wanted to let you know that it isn't fixed yet, it's even slightly worse . Apparently in the September CTP (I've tried the prototype presentation), protected members of sealed classes also appear in the Contents-tab and they can be found using the Search-tab as well.

Michael
r3ganc
Hi Michael,

I appreciate your line of thought. We will open a feature request to provide a "RemoveSealedProtectedMembers.xsl". Just how much priority it gets will depend on user feedback, so if other Sandcastle users agree with Michael, please comment here. It's not too difficult a transformation, so you may want to just make one yourself instead.

If you build reference documentation that way, though, it will no longer agree with Microsoft's practice going forward. The clinching argument in this debate within Microsoft was the case of knowing about overrides, so I will try to explain that more clearly. Suppose you start with a non-sealed class that has a virtual, protected member.

public class Doer {

public virtual void DoSomething () {}

protected virtual void WriteToLog (string message) {}

}

Here the WriteToLog method is protected because it is intended to be used by Doer classes to write log messages as they DoSomething(). Now suppose someone gives you a sealed class MyDoer : Doer. If that class is writing log messages in a non-standard way, you, as a consumer of that class, may be interested to know that. There were several cases in Microsoft libraries where the library creators argued that it was crucial that users of their library classes know whether a protected member had been overridden or not.

Cheers,

David
Fusion1224
Hi David,

I have been talking to a colleague about this problem and it gave me a better understanding of your and my perspective. I believe our difference of opinion comes from the fact that we're talking about different types of classes.

I think your view comes from a control developer's perspective where the base-classes actually does have a meaning for the person using the class.

My case is different. I'm not developing controls, but I am developing business classes. Our base-classes are part of the Object/Relational mapper that we're using. So we need to use the base-classes internally to actually commit the data in the business classes to the database, but the users of my class have no interest in the protected methods of the object relational mapper at all. That's why it's so important that my classes are sealed and why they should never touch these methods. That's also why we don't want them to see these members.

Is this making things a bit more clear

Michael
Protected method of sealed classes appear in the Index

Answer this question