C#编写详细XML注释时VS2015长标签导致悬浮提示不显示问题

在VS2015环境下编写C# XML文档注释时存在稳定复现的异常表现：

• 当<summary>块及关联注释标签内容长度较短时，鼠标悬停在对应变量/类/方法上，Tooltip可正常展示summary注释内容
• 当注释块内包含超长标签属性值（如<see>标签中填入过长的href链接）时，注释解析流程会静默失败，悬浮提示完全不显示。

复现问题的示例代码如下：

/// <summary>
///   Max block size to write to a single event log.
/// </summary>
/// <remarks>
///   Although
///   <see href="https://learn.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的已知Bug，触发根源是IDE内置的XML注释解析器对单个标签属性的长度设置了硬编码阈值，当属性值长度超过约260字符时，整个注释DOM的解析流程会直接终止，没有降级渲染逻辑，最终导致Tooltip无法生成。该Bug在VS2017 15.3及之后的版本中已被官方修复，不存在同类解析问题。

• 方案1：裁剪URL冗余参数
  示例中触发问题的微软文档链接携带了大量VS IDE专属的跳转追踪、环境标记参数，这类参数不影响文档页面的正常访问，全部删除后URL长度可缩短70%以上，远低于解析器的长度阈值，替换原有超长href值即可恢复Tooltip正常显示，且不需要依赖任何第三方服务。
• 方案2：调整标签写法，避免属性位存长内容
  不要把超长URL直接放在<see>标签的href属性位，可将链接作为普通文本放在<remarks>块内，<see>标签仅保留核心说明文字，从根源上避开属性长度限制。
  参考写法：

  /// <summary>
  ///   Max block size to write to a single event log.
  /// </summary>
  /// <remarks>
  ///   Although <see>System.Diagnostics.EventLog.WriteEntry</see> official documentation 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.
  ///   文档链接可直接放在备注普通文本区，不写入标签属性即可避免触发解析Bug。
  ///
  ///   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;
  

• 方案3：升级开发环境
  若团队开发规范允许，升级到VS2017及以上版本可彻底修复该解析缺陷，无需调整现有注释的编写格式。

内容的提问来源于stack exchange，提问作者Adrian