I'm marking classes/methods/properties as obsolete using the ObsoleteAttribute in my source code. I would like
similar behavior to the MSDN documentation, where obsolete methods/classes/properties are clearly shown using red text.
Unfortunately, this just doesn't happen for me. I've checked the XML output from VisualStudio, and it looks like this XML is feeding the appropriate obsolete markers into DocProject/Sandcastle... but I'm not getting anything in the CHM to suggest that stuff
is being marked as obsolete.
Nov 19, 2009 at 1:52 PM
What versions of DocProject and Sandcastle are you using?
It's working for me. In the list topics (such as Types and Members) there's text that reads, "Obsolete.". It renders in red and appears next to types and members that are marked with
System.ObsoleteAttribute in code.
It seems that the output of the MRefBuilder program includes the message argument as well. I was able to improve the documentation by updating the XSL a bit so that it includes the message value. To do that, and also to verify whether your XSL
files are the same as mine, follow these steps:
- Open your project's Help\Presentation\Style\Transforms\utilities_reference.xsl file.
- Alternatively, you can make the necessary changes directly to the file in Sandcastle's installation folder so that it applies to all
new DocProjects and DocSites.
- Find all occurrences of the following sequence of elements:
- Replace each occurrence with the following element:
- At the bottom of the file, before the closing </xsl:stylesheet> tag, insert the following XSL:
Let me know if you still need assistance.
We are using DocProject 22.214.171.124 and Sandcastle 2.4.10520.1. I made the modifications you suggested, but they did not help. We have heavily customized the appearance of the CHM and I feared that we had somehow broken the obsolete labels.
I've spent the past few days trying to track down the cause of the problem and it appears that the obsolete labels dissapear immediately after we uncheck any arbitrary number of Namespace topics in Topic Explorer, immediately after adding an external source.
If it would help, I can try to put together a small project to reproduce the problem?
Nov 26, 2009 at 10:07 AM
Edited Nov 26, 2009 at 10:09 AM
A test project along with step by step instructions on how to repro the issue may be helpful. Send me your email via my contact form and I'll reply with mine:
I probably won't get to it until after the holiday though. In the mean time you may want to try to verify the following on your own:
- After building, open your project's buildhelp\reflection.xml file. (Note that it's not visible in Solution Explorer.)
- Verify that any APIs marked with ObsoleteAttribute are indicated as such with a block of XML like the following.
<value>This is the message that is specified for the ObsoleteAttribute in code.</value>
- Then open your project's Help\Presentation\Style\Transforms\main_sandcastle.xsl file.
- Insert the following XML fragment immediately inside of the
<xsl:template name="body"> element, which can be found near the top of the file.
(This API is obsolete.)
Build again now and you should see a new message above the summary for all obsolete types. For example, a class named
TestObsolete that is marked with ObsoleteAttribute
will have a class topic created that should look something like this:
Members See Also Send Feedback
(Obsolete: This is a test of the ObsoleteAttribute in Sandcastle when used on a type.)
This is a summary
Assembly: TestLibrary (in TestLibrary.dll)
It's not a great presentation, but hopefully it's a start :)