如何在 C# 中編寫更詳細的 XML 注釋？

Question

我正在為一些變量編寫一些 XML 注釋，並發現如果我有一個簡短的摘要塊，當我將鼠標懸停在變量上時，我會得到帶有該摘要的工具提示。 但是，如果我有一個長標簽，它將停止顯示。 這是一個例子：

        /// <summary>
        ///   Max block size to write to a single event log.
        /// </summary>
        /// <remarks>
        ///   Although
        ///   <see href="https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.eventlog.writeentry?view=netframework-4.6&f1url=%3FappId%3DDev14IDEF1%26l%3DEN-US%26k%3Dk(System.Diagnostics.EventLog.WriteEntry)%3Bk(TargetFrameworkMoniker-.NETFramework%2CVersion%253Dv4.6)%3Bk(DevLang-csharp)%26rd%3Dtrue#system-diagnostics-eventlog-writeentry(system-string-system-string-system-diagnostics-eventlogentrytype)"/>
        ///   states that the longest entry can only be 31839 bytes, even if
        ///   the API doesn't actually throw an exception at higher values,
        ///   testing actually shows that it will only accept 31839 - 129 =
        ///   31710 bytes.
        ///
        ///   Also, not all characters are 1 byte in size (assuming UTF8 and not
        ///   Windows UNICODE), so this may not actually work either with larger
        ///   width characters.  Going to assume that 99.999% of the characters
        ///   to be logged are going to be 1 byte in size and also add some
        ///   extra padding to ensure that the log is saved to the Event Log.
        /// </remarks>
        private static readonly int maxEventLogEntrySize = 31839 - 200;

這是 VS2015 的已知錯誤嗎？ 有沒有辦法解決？ 我不能將 tinyurl 放入代碼中。

Answer 1

這不是因為描述很長。 這是因為您的長評論不是格式良好的 XML。 href 屬性中的 URL 在“4.6”之后有一個未轉義的 '&' 字符。 VS 中的注釋解析器無法讀取注釋，因此快速信息中不顯示任何內容。 將您的鏈接更改為：

///   <see href="https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.eventlog.writeentry?view=netframework-4.6%24f1url=%3FappId%3DDev14IDEF1%26l%3DEN-US%26k%3Dk(System.Diagnostics.EventLog.WriteEntry)%3Bk(TargetFrameworkMoniker-.NETFramework%2CVersion%253Dv4.6)%3Bk(DevLang-csharp)%26rd%3Dtrue#system-diagnostics-eventlog-writeentry(system-string-system-string-system-diagnostics-eventlogentrytype)"/>

工具提示將在 VS 2022 上如下所示：

請注意，VS 2015 和 2017 沒有顯示<remarks>標記的內容。 Intellisense 快速信息工具提示中僅顯示<summary> 。 但是從 16.6 左右的版本開始，VS 2019 和 VS 2022 也顯示<remarks> 。

順便說一句，我仍然認為指向 MS 文檔的硬編碼 href 鏈接不是一個好主意。 我會使用標准的 cref 鏈接：

///   <see cref="System.Diagnostics.EventLog.WriteEntry(string, string, EventLogEntryType)"/>