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. 

Any ideas/suggestions?

Hi,

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:

1. Open your project's Help\Presentation\Style\Transforms\utilities_reference.xsl file.
   1. 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.
2. Find all occurrences of the following sequence of elements: 

<xsl:text> </xsl:text>
<include item="obsoleteRed" />

1. Replace each occurrence with the following element: 

<xsl:call-template name="obsolete" />

1. At the bottom of the file, before the closing </xsl:stylesheet> tag, insert the following XSL:

<!-- obsolete -->

 

<xsl:template name="obsolete">

  <xsl:text> </xsl:text>

  <include item="obsoleteRed" />

  <xsl:if test="normalize-space(attributes/attribute[type/@api='T:System.ObsoleteAttribute']/argument/value)">

    <xsl:value-of select="attributes/attribute[type/@api='T:System.ObsoleteAttribute']/argument/value" />

  </xsl:if>

</xsl:template>

Let me know if you still need assistance.

- Dave

Hi Dave,

We are using DocProject 1.11.0.0 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?

William

Hi William,

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:  http://davesexton.com/Contact/

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:

1. After building, open your project's buildhelp\reflection.xml file.  (Note that it's not visible in Solution Explorer.)
2. Verify that any APIs marked with ObsoleteAttribute are indicated as such with a block of XML like the following.
   
   <attribute>
     <type api="T:System.ObsoleteAttribute" ref="true" />
     <argument>
       <type api="T:System.String" ref="true" />
       <value>This is the message that is specified for the ObsoleteAttribute in code.</value>
     </argument>
     ...
   </attribute>
   
3. Then open your project's Help\Presentation\Style\Transforms\main_sandcastle.xsl file.
4. Insert the following XML fragment immediately inside of the <xsl:template name="body"> element, which can be found near the top of the file.
   
   <xsl:variable name="obsolete" select="/document/reference/attributes/attribute[type/@api='T:System.ObsoleteAttribute']" />
   <xsl:if test="$obsolete">
     <xsl:choose>
       <xsl:when test="normalize-space($obsolete/argument/value)">
         (Obsolete: <xsl:value-of select="$obsolete/argument/value" />)
       </xsl:when>
       <xsl:otherwise>
         (This API is obsolete.)
       </xsl:otherwise>
     </xsl:choose>
   </xsl:if>

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:

    TestObsolete Class 
    Members  See Also  Send Feedback 
 
    (Obsolete: This is a test of the ObsoleteAttribute in Sandcastle when used on a type.)
    This is a summary

    Namespace:  TestLibrary
    Assembly:  TestLibrary (in TestLibrary.dll)

It's not a great presentation, but hopefully it's a start :)

- Dave