How to write more detailed XML comments in C#?

Question

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.

score 1 · Accepted Answer · answered Jun 23 '22 at 07:28

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)"/>

Thanks for that. Esp the last comment re using the cref link. — Adrian, Jun 23 '22 at 18:08
Also thanks for bringing to my attention that I need `` tags in my docs. It's too bad that the default document generator doesn't support markdown. Far less intrusive and easier to read, even when not put though the generator. — Adrian, Jun 23 '22 at 19:37

How to write more detailed XML comments in C#?

1 Answers1