Add XML documentation to LoggerMessage generated methods

src/libraries/Microsoft.Extensions.Logging.Abstractions/gen/LoggerMessageGenerator.Emitter.cs

@@ -410,6 +410,8 @@ private void GenLogMethod(LoggerMethod lm, string nestedIndentation)
 ");
                 }
 
+                GenMethodDocumentation(lm, nestedIndentation);
+
                 _builder.Append($@"
         {nestedIndentation}[{s_generatedCodeAttribute}]
         {nestedIndentation}{lm.Modifiers} void {lm.Name}({extension}");
@@ -503,23 +505,113 @@ static string GetLogLevel(LoggerMethod lm)
                     }
                     else
                     {
-                        level = lm.Level switch
-                        {
-                            0 => "global::Microsoft.Extensions.Logging.LogLevel.Trace",
-                            1 => "global::Microsoft.Extensions.Logging.LogLevel.Debug",
-                            2 => "global::Microsoft.Extensions.Logging.LogLevel.Information",
-                            3 => "global::Microsoft.Extensions.Logging.LogLevel.Warning",
-                            4 => "global::Microsoft.Extensions.Logging.LogLevel.Error",
-                            5 => "global::Microsoft.Extensions.Logging.LogLevel.Critical",
-                            6 => "global::Microsoft.Extensions.Logging.LogLevel.None",
-                            _ => $"(global::Microsoft.Extensions.Logging.LogLevel){lm.Level}",
-                        };
+                        level = GetLogLevelFullName(lm.Level.Value);
                     }
 
                     return level;
                 }
             }
 
+            private void GenMethodDocumentation(LoggerMethod lm, string nestedIndentation)
+            {
+                _builder.Append($@"
+        {nestedIndentation}/// <summary>
+        {nestedIndentation}/// <para><b>Message:</b> {EscapeForXmlDoc(lm.Message)}</para>");
+
+                if (lm.Level != null)
+                {
+                    _builder.Append($@"
+        {nestedIndentation}/// <para><b>Level:</b> {GetLogLevelName(lm.Level.Value)}</para>");
+                }
+
+                _builder.Append($@"
+        {nestedIndentation}/// </summary>");
+            }
+
+            private static string EscapeForXmlDoc(string text)
+            {
+                if (string.IsNullOrEmpty(text))
+                {
+                    return text;
+                }
+
+                foreach (char c in text)
+                {
+                    if (c is '<' or '>' or '&' or '"' or '\'' or '\n' or '\r')
+                    {
+                        return PerformEscaping(text);
+                    }
+                }
+
+                return text;
+
+                static string PerformEscaping(string text)
+                {
+                    var sb = new StringBuilder(text.Length + 20);
+                    foreach (char c in text)
+                    {
+                        switch (c)
+                        {
+                            case '<':
+                                sb.Append("&lt;");
+                                break;
+                            case '>':
+                                sb.Append("&gt;");
+                                break;
+                            case '&':
+                                sb.Append("&amp;");
+                                break;
+                            case '"':
+                                sb.Append("&quot;");
+                                break;
+                            case '\'':
+                                sb.Append("&apos;");
+                                break;
+                            case '\n':
+                                sb.Append("&#10;");
+                                break;
+                            case '\r':
+                                sb.Append("&#13;");
+                                break;
+                            default:
+                                sb.Append(c);
+                                break;
+                        }
+                    }
+                    return sb.ToString();
+                }
+            }
+
+            private static string GetLogLevelName(int level)
+            {
+                return level switch
+                {
+                    0 => "Trace",
+                    1 => "Debug",
+                    2 => "Information",
+                    3 => "Warning",
+                    4 => "Error",
+                    5 => "Critical",
+                    6 => "None",
+                    _ => level.ToString(),
+                };
+            }
+
+            private static string GetLogLevelFullName(int level)
+            {
+                return level switch
+                {
+                    0 => "global::Microsoft.Extensions.Logging.LogLevel.Trace",
+                    1 => "global::Microsoft.Extensions.Logging.LogLevel.Debug",
+                    2 => "global::Microsoft.Extensions.Logging.LogLevel.Information",
+                    3 => "global::Microsoft.Extensions.Logging.LogLevel.Warning",
+                    4 => "global::Microsoft.Extensions.Logging.LogLevel.Error",
+                    5 => "global::Microsoft.Extensions.Logging.LogLevel.Critical",
+                    6 => "global::Microsoft.Extensions.Logging.LogLevel.None",
+                    _ => $"(global::Microsoft.Extensions.Logging.LogLevel){level}",
+                };
+            }
+
             private void GenEnumerationHelper()
             {
                 if (_needEnumerationHelper)

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithDefaultValues.generated.txt

@@ -42,6 +42,9 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
             global::System.Collections.IEnumerator global::System.Collections.IEnumerable.GetEnumerator() => GetEnumerator();
         }
 
+        /// <summary>
+        /// <para><b>Message:</b> </para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public static partial void M0(global::Microsoft.Extensions.Logging.ILogger logger, global::Microsoft.Extensions.Logging.LogLevel level)
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithDynamicLogLevel.generated.txt

@@ -42,6 +42,9 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
             global::System.Collections.IEnumerator global::System.Collections.IEnumerable.GetEnumerator() => GetEnumerator();
         }
 
+        /// <summary>
+        /// <para><b>Message:</b> M9</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public static partial void M9(global::Microsoft.Extensions.Logging.LogLevel level, global::Microsoft.Extensions.Logging.ILogger logger)
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithLoggerFromPrimaryConstructor.generated.txt

@@ -9,6 +9,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __M0Callback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Debug, new global::Microsoft.Extensions.Logging.EventId(0, nameof(M0)), "M0", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> M0</para>
+        /// <para><b>Level:</b> Debug</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public partial void M0()
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithLoggerFromPrimaryConstructorWithParameterUsedInMethod.generated.txt

@@ -9,6 +9,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __M0Callback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Debug, new global::Microsoft.Extensions.Logging.EventId(0, nameof(M0)), "M0", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> M0</para>
+        /// <para><b>Level:</b> Debug</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public partial void M0()
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithLoggerInFieldAndFromPrimaryConstructor.generated.txt

@@ -9,6 +9,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __M0Callback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Debug, new global::Microsoft.Extensions.Logging.EventId(0, nameof(M0)), "M0", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> M0</para>
+        /// <para><b>Level:</b> Debug</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public partial void M0()
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithMoreThan6Params.generated.txt

@@ -75,6 +75,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
             global::System.Collections.IEnumerator global::System.Collections.IEnumerable.GetEnumerator() => GetEnumerator();
         }
 
+        /// <summary>
+        /// <para><b>Message:</b> M9 {p1} {p2} {p3} {p4} {p5} {p6} {p7}</para>
+        /// <para><b>Level:</b> Error</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public static partial void Method9(global::Microsoft.Extensions.Logging.ILogger logger, global::System.Int32 p1, global::System.Int32 p2, global::System.Int32 p3, global::System.Int32 p4, global::System.Int32 p5, global::System.Int32 p6, global::System.Collections.Generic.IEnumerable<global::System.Int32> p7)
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithMultipleClassesStableOrder.generated.txt

@@ -9,6 +9,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __LogACallback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Debug, new global::Microsoft.Extensions.Logging.EventId(1, nameof(LogA)), "Message from ClassA", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> Message from ClassA</para>
+        /// <para><b>Level:</b> Debug</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         static partial void LogA(global::Microsoft.Extensions.Logging.ILogger logger)
         {
@@ -27,6 +31,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __LogBCallback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Information, new global::Microsoft.Extensions.Logging.EventId(2, nameof(LogB)), "Message from ClassB", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> Message from ClassB</para>
+        /// <para><b>Level:</b> Information</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         static partial void LogB(global::Microsoft.Extensions.Logging.ILogger logger)
         {
@@ -45,6 +53,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __LogCCallback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Warning, new global::Microsoft.Extensions.Logging.EventId(3, nameof(LogC)), "Message from ClassC", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> Message from ClassC</para>
+        /// <para><b>Level:</b> Warning</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         static partial void LogC(global::Microsoft.Extensions.Logging.ILogger logger)
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithNestedClass.generated.txt

@@ -19,6 +19,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses.NestedNamesp
                             private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __M9Callback =
                                 global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Debug, new global::Microsoft.Extensions.Logging.EventId(9, nameof(M9)), "M9", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+                            /// <summary>
+                            /// <para><b>Message:</b> M9</para>
+                            /// <para><b>Level:</b> Debug</para>
+                            /// </summary>
                             [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
                             public static partial void M9(global::Microsoft.Extensions.Logging.ILogger logger)
                             {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithNestedClassWithGenericTypesWithAttributes.generated.txt

@@ -11,6 +11,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
             private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, A, B, C, global::System.Exception?> __M0Callback =
                 global::Microsoft.Extensions.Logging.LoggerMessage.Define<A, B, C>(global::Microsoft.Extensions.Logging.LogLevel.Debug, new global::Microsoft.Extensions.Logging.EventId(42, nameof(M0)), "a = {a}; b = {b}; c = {c}", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+            /// <summary>
+            /// <para><b>Message:</b> a = {a}; b = {b}; c = {c}</para>
+            /// <para><b>Level:</b> Debug</para>
+            /// </summary>
             [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
             public static partial void M0(global::Microsoft.Extensions.Logging.ILogger logger, A a, B b, C c)
             {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithSkipEnabledCheck.generated.txt

@@ -9,6 +9,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Exception?> __M0Callback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define(global::Microsoft.Extensions.Logging.LogLevel.Information, new global::Microsoft.Extensions.Logging.EventId(0, nameof(M0)), "Message: When using SkipEnabledCheck, the generated code skips logger.IsEnabled(logLevel) check before calling log. To be used when consumer has already guarded logger method in an IsEnabled check.", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> Message: When using SkipEnabledCheck, the generated code skips logger.IsEnabled(logLevel) check before calling log. To be used when consumer has already guarded logger method in an IsEnabled check.</para>
+        /// <para><b>Level:</b> Information</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public static partial void M0(global::Microsoft.Extensions.Logging.ILogger logger)
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/Baselines/TestWithTwoParams.generated.txt

@@ -9,6 +9,10 @@ namespace Microsoft.Extensions.Logging.Generators.Tests.TestClasses
         private static readonly global::System.Action<global::Microsoft.Extensions.Logging.ILogger, global::System.Int32, global::System.Collections.Generic.IEnumerable<global::System.Int32>, global::System.Exception?> __M0Callback =
             global::Microsoft.Extensions.Logging.LoggerMessage.Define<global::System.Int32, global::System.Collections.Generic.IEnumerable<global::System.Int32>>(global::Microsoft.Extensions.Logging.LogLevel.Error, new global::Microsoft.Extensions.Logging.EventId(0, nameof(M0)), "M0 {a1} {a2}", new global::Microsoft.Extensions.Logging.LogDefineOptions() { SkipEnabledCheck = true });
 
+        /// <summary>
+        /// <para><b>Message:</b> M0 {a1} {a2}</para>
+        /// <para><b>Level:</b> Error</para>
+        /// </summary>
         [global::System.CodeDom.Compiler.GeneratedCodeAttribute("Microsoft.Extensions.Logging.Generators", "%VERSION%")]
         public static partial void M0(global::Microsoft.Extensions.Logging.ILogger logger, global::System.Int32 a1, global::System.Collections.Generic.IEnumerable<global::System.Int32> a2)
         {

src/libraries/Microsoft.Extensions.Logging.Abstractions/tests/Microsoft.Extensions.Logging.Generators.Tests/LoggerMessageGeneratorParserTests.cs

@@ -1051,7 +1051,7 @@ partial class C
             // Make sure compilation was successful.
             Assert.Empty(diagnostics);
             Assert.Equal(1, generatedSources.Length);
-            Assert.Equal(21, generatedSources[0].SourceText.Lines.Count);
+            Assert.Equal(25, generatedSources[0].SourceText.Lines.Count);
         }
         [Theory]
         [InlineData("{request}", "request")]