How can I provide XML comments documentation without ruining readability within object browser?

Question

I am working to enhance some of our source code commenting to improve the quality of the SandCastle-generated class library reference docs by adding additional entries like <seealso> or <example> with <code>.

Basic XML comments work fine in both the Object Browser and also in the SandCastle-generated help docs.

However, if I add any tags like <seealso> or <example>, the Object Browser does a terrible job of rendering it.

Here's an example:

C#

/// <summary>
    /// Represents the view mode that displays data in table layout 
    /// for the <see cref="ItemsMultiView"/> control
    /// <remarks>This class must be used within an <see cref="ItemsMultiView"/>; 
    /// it cannot be used alone</remarks>
    /// <example>
    ///<para>
    ///            The following example shows how to define a TableView 
    ///            to support the Table <see cref="ItemsMultiView.ViewMode" />.  
    ///            Note the use of <see cref="TableViewColumn.IsReadOnly" /> 
    ///            to disable editing ofcells on a per-column basis.
    ///        </para>
    ///        <code language="xml" xmlns:acme="http://schemas.acme.com/2010/xaml/presentation">
    ///            <acme:ItemsMultiView
    ///                CanUserSortItems="True"
    ///                ItemsSource="{Binding Employees}"
    ///                SelectionMode="Multiple">
    ///<acme:ItemsMultiView.TableView>
    ///    <acme:TableView CanUserReorderColumns="True"
    ///                        CanUserResizeColumns="True">
    ///        <acme:TableView.Columns>
    ///            <acme:TableViewTextColumn Binding="{Binding FirstName}"
    ///                                        Header="First Name"
    ///                                        IsReadOnly="True" />
    ///            <acme:TableViewTextColumn Binding="{Binding LastName}"
    ///                                        Header="Last Name"
    ///                                        IsReadOnly="True" />
    ///            <acme:TableViewDateColumn Binding="{Binding BirthDate}"
    ///                                        DateMode="DateAndTime"
    ///                                        Header="Birthday" />
    ///            <acme:TableViewCheckBoxColumn Binding="{Binding WorksWeekends}" Header="Works Weekends" />
    ///        </acme:TableView.Columns>
    ///    </acme:TableView>
    ///</acme:ItemsMultiView.TableView>
    ///</acme:ItemsMultiView>
    ///        </code>
    /// </example>
    /// <seealso cref="5b8ce9ab-7703-4b85-8dbf-d74a2cc2fac3.htm"/>
    /// </summary>
    public class TableView : ViewBase
    {

Here's what it looks like in the Object Browser:

public class TableView : Acme.Windows.Controls.ViewBase

Member of Acme.Windows.Controls

Summary:

Represents the view mode that displays data in table layout for the ItemsMultiView control This class must be used within an ItemsMultiView; it cannot be used alone

The following example shows how to define a TableView to support the Table ItemsMultiView.ViewMode. Note the use of TableViewColumn.IsReadOnly to disable editing ofcells on a per-column basis. 5b8ce9ab-7703-4b85-8dbf-d74a2cc2fac3.htm

Remarks:

This class must be used within an ItemsMultiView; it cannot be used alone

It seems to be a limitation of Object Browser that it doesn't support rendering of things like Examples or See cref links.

Is that true, and if so, what can I do to get Object Browser to totally ignore the tags that are causing problems instead of only partially displaying them?

Am I required to maintain two versions of the XML comments (one for Object Browser compatibility, and one for SandCastle documentation?)

Answer 1

The code in the example above is not structured correctly. The Summary tag should only contain summary information, and the other tags should exist as siblings to the Summary tag.

Once I corrected this, the behavior is as expected.