如何在不破壞對象瀏覽器內的可讀性的情況下提供XML註釋文檔？

我的工作，以提高我們的一些源代碼註釋通過添加額外的條目像<seealso>或<例如>與<代碼>改善沙塔生成的類庫引用文檔的質量。如何在不破壞對象瀏覽器內的可讀性的情況下提供XML註釋文檔？

基本XML註釋在對象瀏覽器和SandCastle生成的幫助文檔中都能正常工作。

但是，如果我添加任何標籤，如<seealso>或<示例>，對象瀏覽器執行渲染它的可怕工作。

下面是一個例子：

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內使用;它不能單獨使用

它似乎是對象瀏覽器的一個限制，它不支持渲染諸如Examples或See cref鏈接之類的東西。

這是真的嗎？如果是這樣，我能做些什麼來使對象瀏覽器完全忽略導致問題的標籤而不是部分顯示它們？

我是否需要維持XML註釋的兩個版本（一個用於對象瀏覽器兼容性，以及一個用於沙堡文檔？）

來源

2012-03-27 Joseph Gabriel

在上面的例子中是不正確結構的代碼。 Summary標籤應該只包含摘要信息，其他標籤應該以摘要標籤的同級形式存在。

一旦我糾正了這一點，行爲就像預期的那樣。

來源

2012-03-27 18:40:46

嗯......當我將我的seealso標籤移到摘要之外時，它只是將其從對象瀏覽器完全移除。 – edsobo 2013-03-08 17:25:54

如何在不破壞對象瀏覽器內的可讀性的情況下提供XML註釋文檔？

回答

相關問題