Added support for <summary> XML docs for generated commands

Sergio0694 · Sergio0694 · commit 2e8149f2a375 · 2021-07-21T02:32:11.000+02:00
diff --git a/Microsoft.Toolkit.Mvvm.SourceGenerators/Input/ICommandGenerator.SyntaxReceiver.cs b/Microsoft.Toolkit.Mvvm.SourceGenerators/Input/ICommandGenerator.SyntaxReceiver.cs
@@ -22,12 +22,12 @@ private sealed class SyntaxReceiver : ISyntaxContextReceiver
             /// <summary>
             /// The list of info gathered during exploration.
             /// </summary>
-            private readonly List<IMethodSymbol> gatheredInfo = new();
+            private readonly List<Item> gatheredInfo = new();
 
             /// <summary>
             /// Gets the collection of gathered info to process.
             /// </summary>
-            public IReadOnlyCollection<IMethodSymbol> GatheredInfo => this.gatheredInfo;
+            public IReadOnlyCollection<Item> GatheredInfo => this.gatheredInfo;
 
             /// <inheritdoc/>
             public void OnVisitSyntaxNode(GeneratorSyntaxContext context)
@@ -37,9 +37,16 @@ public void OnVisitSyntaxNode(GeneratorSyntaxContext context)
                     context.SemanticModel.Compilation.GetTypeByMetadataName(typeof(ICommandAttribute).FullName) is INamedTypeSymbol iCommandSymbol &&
                     methodSymbol.GetAttributes().Any(a => SymbolEqualityComparer.Default.Equals(a.AttributeClass, iCommandSymbol)))
                 {
-                    this.gatheredInfo.Add(methodSymbol);
+                    this.gatheredInfo.Add(new Item(methodDeclaration.GetLeadingTrivia(), methodSymbol));
                 }
             }
+
+            /// <summary>
+            /// A model for a group of item representing a discovered type to process.
+            /// </summary>
+            /// <param name="LeadingTrivia">The leading trivia for the field declaration.</param>
+            /// <param name="MethodSymbol">The <see cref="IMethodSymbol"/> instance for the target method.</param>
+            public sealed record Item(SyntaxTriviaList LeadingTrivia, IMethodSymbol MethodSymbol);
         }
     }
 }
diff --git a/Microsoft.Toolkit.Mvvm.SourceGenerators/Input/ICommandGenerator.cs b/Microsoft.Toolkit.Mvvm.SourceGenerators/Input/ICommandGenerator.cs
@@ -8,6 +8,7 @@
 using System.Diagnostics.Contracts;
 using System.Linq;
 using System.Text;
+using System.Text.RegularExpressions;
 using Microsoft.CodeAnalysis;
 using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
@@ -43,7 +44,7 @@ public void Execute(GeneratorExecutionContext context)
                 return;
             }
 
-            foreach (var items in syntaxReceiver.GatheredInfo.GroupBy<IMethodSymbol, INamedTypeSymbol>(static item => item.ContainingType, SymbolEqualityComparer.Default))
+            foreach (var items in syntaxReceiver.GatheredInfo.GroupBy<SyntaxReceiver.Item, INamedTypeSymbol>(static item => item.MethodSymbol.ContainingType, SymbolEqualityComparer.Default))
             {
                 if (items.Key.DeclaringSyntaxReferences.Length > 0 &&
                     items.Key.DeclaringSyntaxReferences.First().GetSyntax() is ClassDeclarationSyntax classDeclaration)
@@ -66,12 +67,12 @@ public void Execute(GeneratorExecutionContext context)
         /// <param name="context">The input <see cref="GeneratorExecutionContext"/> instance to use.</param>
         /// <param name="classDeclaration">The <see cref="ClassDeclarationSyntax"/> node to process.</param>
         /// <param name="classDeclarationSymbol">The <see cref="INamedTypeSymbol"/> for <paramref name="classDeclaration"/>.</param>
-        /// <param name="methodSymbols">The sequence of <see cref="IMethodSymbol"/> instances to process.</param>
+        /// <param name="items">The sequence of <see cref="IMethodSymbol"/> instances to process.</param>
         private static void OnExecute(
             GeneratorExecutionContext context,
             ClassDeclarationSyntax classDeclaration,
             INamedTypeSymbol classDeclarationSymbol,
-            IEnumerable<IMethodSymbol> methodSymbols)
+            IEnumerable<SyntaxReceiver.Item> items)
         {
             // Create the class declaration for the user type. This will produce a tree as follows:
             //
@@ -82,7 +83,7 @@ private static void OnExecute(
             var classDeclarationSyntax =
                 ClassDeclaration(classDeclarationSymbol.Name)
                 .WithModifiers(classDeclaration.Modifiers)
-                .AddMembers(methodSymbols.Select(item => CreateCommandMembers(context, default, item)).SelectMany(static g => g).ToArray());
+                .AddMembers(items.Select(item => CreateCommandMembers(context, item.LeadingTrivia, item.MethodSymbol)).SelectMany(static g => g).ToArray());
 
             TypeDeclarationSyntax typeDeclarationSyntax = classDeclarationSyntax;
 
@@ -158,6 +159,27 @@ private static IEnumerable<MemberDeclarationSyntax> CreateCommandMembers(Generat
                         AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ICommandGenerator).FullName))),
                         AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ICommandGenerator).Assembly.GetName().Version.ToString())))))));
 
+            SyntaxTriviaList summaryTrivia = SyntaxTriviaList.Empty;
+
+            // Parse the <summary> docs, if present
+            foreach (SyntaxTrivia trivia in leadingTrivia)
+            {
+                if (trivia.IsKind(SyntaxKind.SingleLineCommentTrivia) ||
+                    trivia.IsKind(SyntaxKind.SingleLineDocumentationCommentTrivia))
+                {
+                    string text = trivia.ToString();
+
+                    Match match = Regex.Match(text, @"<summary>.*?<\/summary>", RegexOptions.Singleline);
+
+                    if (match.Success)
+                    {
+                        summaryTrivia = TriviaList(Comment($"/// {match.Value}"));
+
+                        break;
+                    }
+                }
+            }
+
             // Construct the generated property as follows (the explicit delegate cast is needed to avoid overload resolution conflicts):
             //
             // <METHOD_SUMMARY>
@@ -175,7 +197,8 @@ private static IEnumerable<MemberDeclarationSyntax> CreateCommandMembers(Generat
                         Attribute(IdentifierName("global::System.CodeDom.Compiler.GeneratedCode"))
                         .AddArgumentListArguments(
                             AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ICommandGenerator).FullName))),
-                            AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ICommandGenerator).Assembly.GetName().Version.ToString())))))),
+                            AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ICommandGenerator).Assembly.GetName().Version.ToString()))))))
+                    .WithOpenBracketToken(Token(summaryTrivia, SyntaxKind.OpenBracketToken, TriviaList())),
                     AttributeList(SingletonSeparatedList(Attribute(IdentifierName("global::System.Diagnostics.DebuggerNonUserCode")))),
                     AttributeList(SingletonSeparatedList(Attribute(IdentifierName("global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage")))))
                 .WithExpressionBody(
diff --git a/UnitTests/UnitTests.NetCore/Mvvm/Test_ICommandAttribute.cs b/UnitTests/UnitTests.NetCore/Mvvm/Test_ICommandAttribute.cs
@@ -51,18 +51,25 @@ public sealed partial class MyViewModel
         {
             public int Counter { get; private set; }
 
+            /// <summary>This is a single line summary.</summary>
             [ICommand]
             private void IncrementCounter()
             {
                 Counter++;
             }
 
+            /// <summary>
+            /// This is a multiline summary
+            /// </summary>
             [ICommand]
             private void IncrementCounterWithValue(int count)
             {
                 Counter += count;
             }
 
+            /// <summary>This is single line with also other stuff below</summary>
+            /// <returns>Foo bar baz</returns>
+            /// <returns>A task</returns>
             [ICommand]
             private async Task DelayAndIncrementCounterAsync()
             {
@@ -71,6 +78,11 @@ private async Task DelayAndIncrementCounterAsync()
                 Counter += 1;
             }
 
+            /// <summary>
+            /// This is multi line with also other stuff below
+            /// </summary>
+            /// <returns>Foo bar baz</returns>
+            /// <returns>A task</returns>
             [ICommand]
             private async Task DelayAndIncrementCounterWithTokenAsync(CancellationToken token)
             {
@@ -79,6 +91,7 @@ private async Task DelayAndIncrementCounterWithTokenAsync(CancellationToken toke
                 Counter += 1;
             }
 
+            // This should not be ported over
             [ICommand]
             private async Task DelayAndIncrementCounterWithValueAsync(int count)
             {

Original file line number	Diff line number	Diff line change
`@@ -22,12 +22,12 @@ private sealed class SyntaxReceiver : ISyntaxContextReceiver`
`22`	`22`	`/// <summary>`
`23`	`23`	`/// The list of info gathered during exploration.`
`24`	`24`	`/// </summary>`
`25`		`- private readonly List<IMethodSymbol> gatheredInfo = new();`
	`25`	`+ private readonly List<Item> gatheredInfo = new();`
`26`	`26`
`27`	`27`	`/// <summary>`
`28`	`28`	`/// Gets the collection of gathered info to process.`
`29`	`29`	`/// </summary>`
`30`		`- public IReadOnlyCollection<IMethodSymbol> GatheredInfo => this.gatheredInfo;`
	`30`	`+ public IReadOnlyCollection<Item> GatheredInfo => this.gatheredInfo;`
`31`	`31`
`32`	`32`	`/// <inheritdoc/>`
`33`	`33`	`public void OnVisitSyntaxNode(GeneratorSyntaxContext context)`
`@@ -37,9 +37,16 @@ public void OnVisitSyntaxNode(GeneratorSyntaxContext context)`
`37`	`37`	`context.SemanticModel.Compilation.GetTypeByMetadataName(typeof(ICommandAttribute).FullName) is INamedTypeSymbol iCommandSymbol &&`
`38`	`38`	`methodSymbol.GetAttributes().Any(a => SymbolEqualityComparer.Default.Equals(a.AttributeClass, iCommandSymbol)))`
`39`	`39`	`{`
`40`		`- this.gatheredInfo.Add(methodSymbol);`
	`40`	`+ this.gatheredInfo.Add(new Item(methodDeclaration.GetLeadingTrivia(), methodSymbol));`
`41`	`41`	`}`
`42`	`42`	`}`
	`43`	`+`
	`44`	`+ /// <summary>`
	`45`	`+ /// A model for a group of item representing a discovered type to process.`
	`46`	`+ /// </summary>`
	`47`	`+ /// <param name="LeadingTrivia">The leading trivia for the field declaration.</param>`
	`48`	`+ /// <param name="MethodSymbol">The <see cref="IMethodSymbol"/> instance for the target method.</param>`
	`49`	`+ public sealed record Item(SyntaxTriviaList LeadingTrivia, IMethodSymbol MethodSymbol);`
`43`	`50`	`}`
`44`	`51`	`}`
`45`	`52`	`}`
Original file line number	Diff line number	Diff line change
`@@ -51,18 +51,25 @@ public sealed partial class MyViewModel`
`51`	`51`	`{`
`52`	`52`	`public int Counter { get; private set; }`
`53`	`53`
	`54`	`+ /// <summary>This is a single line summary.</summary>`
`54`	`55`	`[ICommand]`
`55`	`56`	`private void IncrementCounter()`
`56`	`57`	`{`
`57`	`58`	`Counter++;`
`58`	`59`	`}`
`59`	`60`
	`61`	`+ /// <summary>`
	`62`	`+ /// This is a multiline summary`
	`63`	`+ /// </summary>`
`60`	`64`	`[ICommand]`
`61`	`65`	`private void IncrementCounterWithValue(int count)`
`62`	`66`	`{`
`63`	`67`	`Counter += count;`
`64`	`68`	`}`
`65`	`69`
	`70`	`+ /// <summary>This is single line with also other stuff below</summary>`
	`71`	`+ /// <returns>Foo bar baz</returns>`
	`72`	`+ /// <returns>A task</returns>`
`66`	`73`	`[ICommand]`
`67`	`74`	`private async Task DelayAndIncrementCounterAsync()`
`68`	`75`	`{`
`@@ -71,6 +78,11 @@ private async Task DelayAndIncrementCounterAsync()`
`71`	`78`	`Counter += 1;`
`72`	`79`	`}`
`73`	`80`
	`81`	`+ /// <summary>`
	`82`	`+ /// This is multi line with also other stuff below`
	`83`	`+ /// </summary>`
	`84`	`+ /// <returns>Foo bar baz</returns>`
	`85`	`+ /// <returns>A task</returns>`
`74`	`86`	`[ICommand]`
`75`	`87`	`private async Task DelayAndIncrementCounterWithTokenAsync(CancellationToken token)`
`76`	`88`	`{`
`@@ -79,6 +91,7 @@ private async Task DelayAndIncrementCounterWithTokenAsync(CancellationToken toke`
`79`	`91`	`Counter += 1;`
`80`	`92`	`}`
`81`	`93`
	`94`	`+ // This should not be ported over`
`82`	`95`	`[ICommand]`
`83`	`96`	`private async Task DelayAndIncrementCounterWithValueAsync(int count)`
`84`	`97`	`{`