I was writing some XML comments for some variables and discovered that if I have a short summary block, when I hover over the variable I get tooltip with that summary. However, if I have a long tag it stops showing. Here's an example:
/// <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;
Is this a known bug with VS2015? Is there any way around this? I can't be putting tinyurl's in the code.
It's not because the description is long. It's because your long comment is not well-formed XML. The URL in the href attribute has an unescaped '&' character right after "4.6". The comment parser in VS fails to read the comment and thus nothing is displayed in the quick info. Change your link to:
/// <see href="https://learn.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)"/>
The tooltip will then look as follows on VS 2022:
Note that VS 2015 and 2017 didn't display the contents of the <remarks>
tags. Only <summary>
was displayed in the Intellisense quick info tooltip. But starting with version around 16.6, VS 2019 and VS 2022 show also <remarks>
.
BTW, I still think the hardcoded href link to MS docs is not a good idea. I would use the standard cref link:
/// <see cref="System.Diagnostics.EventLog.WriteEntry(string, string, EventLogEntryType)"/>