Question

我正在努力增强一些源代码注释，通过添加其他条目（例如＆lt; seealso＆gt;）来提高SandCastle生成的类库参考文档的质量。或者＆lt; example＆gt;与＆lt; code＆gt;。

基本XML注释在对象浏览器和SandCastle生成的帮助文档中都可以正常工作。

但是，如果我添加任何标签，例如＆lt; seealso＆gt;或者＆lt; example＆gt;，对象浏览器在呈现它时做得非常糟糕。

以下是一个例子：

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
    {

以下是对象浏览器中的内容：

公共类 TableView：Acme.Windows.Controls.ViewBase


Acme.Windows.Controls
的成员

要点：

表示在ItemsMultiView控件的表布局中显示数据的视图模式此类必须在ItemsMultiView中使用;它不能单独使用

以下示例显示如何定义TableView以支持Table ItemsMultiView.ViewMode。请注意使用TableViewColumn.IsReadOnly禁用每列的单元格编辑。   5b8ce9ab-7703-4b85-8dbf-d74a2cc2fac3.htm

说明：

此类必须在ItemsMultiView中使用;它不能单独使用

似乎是对象浏览器的一个限制，它不支持渲染诸如示例或查看cref链接之类的东西。

是真的，如果是这样，我该怎么做才能让对象浏览器完全忽略导致问题的标签，而不是仅部分显示它们？

我是否需要维护两个版本的XML注释（一个用于对象浏览器兼容，一个用于SandCastle文档？）

Answer 1

上例中的代码结构不正确。摘要标记应仅包含摘要信息，其他标记应作为摘要标记的兄弟存在。

一旦我纠正了这个，行为就像预期的那样。

如何在不破坏对象浏览器中的可读性的情况下提供XML注释文档？

1 个答案: