Как я могу предоставить документацию с XML-комментариями, не нарушая читабельность в браузере объектов?

Question

Я работаю над улучшением некоторых наших комментариев к исходному коду, чтобы улучшить качество сгенерированных SandCastle справочных документов по библиотекам классов, добавив дополнительные записи, такие как или с /// <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 {

Вот как это выглядит в браузере объектов:

открытый класс 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?)

Answer 1

Код в приведенном выше примере неправильно структурирован. Тег Summary должен содержать только сводную информацию, а другие теги должны существовать как одноуровневые элементы тега Summary.

Как только я исправил это, поведение, как ожидалось.