Я работаю над улучшением некоторых наших комментариев к исходному коду, чтобы улучшить качество сгенерированных SandCastle справочных документов по библиотекам классов, добавляя дополнительные записи, такие как или с .</p>
<p>Basic XML comments work fine in both the Object Browser and also in the SandCastle-generated help docs.</p>
<p>However, if I add any tags like <seealso> or <example>, the Object Browser does a terrible job of rendering it.</p>
<p>Here's an example:</p>
<p>C#</p>
<pre><code>
/// <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>
///
///
///
///
открытый класс TableView: ViewBase
{
Вот как это выглядит в Обозревателе объектов:
открытый класс TableView: Acme.Windows.Controls.ViewBase
Член Acme.Windows.Controls
Резюме:
Представляет режим просмотра, который отображает данные в макете таблицы для элемента управления ItemsMultiView. Этот класс должен использоваться внутри ItemsMultiView; его нельзя использовать один
В следующем примере показано, как определить TableView для поддержки Table ItemsMultiView.ViewMode. Обратите внимание на использование TableViewColumn.IsReadOnly для отключения редактирования ячеек для каждого столбца.
5b8ce9ab-7703-4b85-8dbf-d74a2cc2fac3.htm
Примечания:
Этот класс должен использоваться внутри ItemsMultiView; нельзя использовать один
Кажется, что ограничение Object Browser заключается в том, что он не поддерживает рендеринг таких вещей, как Example или See cref links.
Это правда, и если да, что я могу сделать, чтобы Object Browser полностью игнорировал теги, которые вызывают проблемы, а не только частично отображал их?
Требуется ли поддерживать две версии комментариев XML (одну для совместимости с Object Browser и одну для документации SandCastle?)