Recompute the XmlDocs when method signature is updated (#7240)

JoshLove-msft · web-flow · commit 182ece6fcfa0 · 2025-05-06T20:31:23.000Z
Contributes to Azure/azure-sdk-for-net#49632
diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/ConstructorProvider.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/ConstructorProvider.cs
@@ -37,7 +37,7 @@ public ConstructorProvider(ConstructorSignature signature, MethodBodyStatement b
         {
             Signature = signature;
             bool skipParamValidation = !signature.Modifiers.HasFlag(MethodSignatureModifiers.Public);
-            var paramHash = MethodProviderHelpers.GetParamhash(signature.Parameters, skipParamValidation);
+            var paramHash = MethodProviderHelpers.GetParamHash(signature.Parameters, skipParamValidation);
             BodyStatements = MethodProviderHelpers.GetBodyStatementWithValidation(signature.Parameters, bodyStatements, paramHash);
             XmlDocs = xmlDocProvider ?? MethodProviderHelpers.BuildXmlDocs(signature.Parameters, signature.Description, null, paramHash);
             EnclosingType = enclosingType;
diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/MethodProvider.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Providers/MethodProvider.cs
@@ -15,7 +15,9 @@ public class MethodProvider
         public MethodSignature Signature { get; private set; }
         public MethodBodyStatement? BodyStatements { get; private set;}
         public ValueExpression? BodyExpression { get; private set;}
-        public XmlDocProvider? XmlDocs { get; private set;}
+
+        public XmlDocProvider? XmlDocs => _xmlDocs ??= BuildXmlDocs();
+        private XmlDocProvider? _xmlDocs;
 
         public TypeProvider EnclosingType { get; }
 
@@ -37,9 +39,9 @@ public MethodProvider(MethodSignature signature, MethodBodyStatement bodyStateme
         {
             Signature = signature;
             bool skipParamValidation = !signature.Modifiers.HasFlag(MethodSignatureModifiers.Public);
-            var paramHash = MethodProviderHelpers.GetParamhash(signature.Parameters, skipParamValidation);
+            var paramHash = MethodProviderHelpers.GetParamHash(signature.Parameters, skipParamValidation);
             BodyStatements = MethodProviderHelpers.GetBodyStatementWithValidation(signature.Parameters, bodyStatements, paramHash);
-            XmlDocs = xmlDocProvider ?? MethodProviderHelpers.BuildXmlDocs(signature.Parameters, signature.Description, signature.ReturnDescription, paramHash);
+            _xmlDocs = xmlDocProvider;
             EnclosingType = enclosingType;
         }
 
@@ -54,10 +56,23 @@ public MethodProvider(MethodSignature signature, ValueExpression bodyExpression,
         {
             Signature = signature;
             BodyExpression = bodyExpression;
-            XmlDocs = xmlDocProvider ?? MethodProviderHelpers.BuildXmlDocs(signature.Parameters, signature.Description, signature.ReturnDescription, null);
+            _xmlDocs = xmlDocProvider;
             EnclosingType = enclosingType;
         }
 
+        private XmlDocProvider? BuildXmlDocs()
+        {
+            return MethodProviderHelpers.BuildXmlDocs(
+                Signature.Parameters,
+                Signature.Description,
+                Signature.ReturnDescription,
+                BodyStatements != null ?
+                    MethodProviderHelpers.GetParamHash(
+                        Signature.Parameters,
+                        !Signature.Modifiers.HasFlag(MethodSignatureModifiers.Public)) :
+                    null);
+        }
+
         public void Update(
             MethodSignature? signature = null,
             MethodBodyStatement? bodyStatements = null,
@@ -67,6 +82,8 @@ public void Update(
             if (signature != null)
             {
                 Signature = signature;
+                // rebuild the XML docs if the signature changes
+                _xmlDocs = BuildXmlDocs();
             }
             if (bodyStatements != null)
             {
@@ -80,7 +97,7 @@ public void Update(
             }
             if (xmlDocProvider != null)
             {
-                XmlDocs = xmlDocProvider;
+                _xmlDocs = xmlDocProvider;
             }
         }
     }
diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/MethodProviderHelpers.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/src/Utilities/MethodProviderHelpers.cs
@@ -12,7 +12,7 @@ namespace Microsoft.TypeSpec.Generator
 {
     internal static class MethodProviderHelpers
     {
-        public static Dictionary<ParameterValidationType, List<ParameterProvider>>? GetParamhash(IEnumerable<ParameterProvider> parameters, bool skipParamValidation)
+        public static Dictionary<ParameterValidationType, List<ParameterProvider>>? GetParamHash(IEnumerable<ParameterProvider> parameters, bool skipParamValidation)
         {
             Dictionary<ParameterValidationType, List<ParameterProvider>>? paramHash = null;
             if (!skipParamValidation)
diff --git a/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/MethodProviderTests.cs b/packages/http-client-csharp/generator/Microsoft.TypeSpec.Generator/test/Providers/MethodProviderTests.cs
@@ -61,13 +61,26 @@ public void TestUpdate()
             typeProvider.Update(methods: [methodProvider]);
 
             // now update the method and check if the type provider reflects the change
-            methodProvider.Update(new MethodSignature("Updated", $"", MethodSignatureModifiers.Public, null, $"", []));
+            methodProvider.Update(new MethodSignature("Updated", $"", MethodSignatureModifiers.Public, null, $"", [new ParameterProvider("foo", $"Foo description", typeof(int))]));
             var updatedMethods = typeProvider.CanonicalView.Methods;
             Assert.IsNotNull(updatedMethods);
             Assert.AreEqual(1, updatedMethods!.Count);
 
+            // Validate that the method name is updated
             var updatedMethod = updatedMethods[0];
             Assert.AreEqual("Updated", updatedMethod.Signature.Name);
+
+            // Validate that the parameter description is updated
+            var parameter = updatedMethod.Signature.Parameters[0];
+            Assert.AreEqual("Foo description", parameter.Description.ToString());
+            Assert.IsTrue(parameter.Type.Equals(typeof(int)));
+
+            // Validate that the xml docs are updated
+            Assert.IsNotNull(updatedMethod.XmlDocs);
+            var xmlDocParamStatement = updatedMethod.XmlDocs!.Parameters[0];
+            Assert.IsNotNull(xmlDocParamStatement);
+            Assert.AreEqual(parameter, xmlDocParamStatement.Parameter);
+            Assert.AreEqual("/// <param name=\"foo\"> Foo description. </param>\n", xmlDocParamStatement.ToDisplayString());
         }
 
         private class TestTypeProvider : TypeProvider

Original file line number	Diff line number	Diff line change
`@@ -37,7 +37,7 @@ public ConstructorProvider(ConstructorSignature signature, MethodBodyStatement b`
`37`	`37`	`{`
`38`	`38`	`Signature = signature;`
`39`	`39`	`bool skipParamValidation = !signature.Modifiers.HasFlag(MethodSignatureModifiers.Public);`
`40`		`- var paramHash = MethodProviderHelpers.GetParamhash(signature.Parameters, skipParamValidation);`
	`40`	`+ var paramHash = MethodProviderHelpers.GetParamHash(signature.Parameters, skipParamValidation);`
`41`	`41`	`BodyStatements = MethodProviderHelpers.GetBodyStatementWithValidation(signature.Parameters, bodyStatements, paramHash);`
`42`	`42`	`XmlDocs = xmlDocProvider ?? MethodProviderHelpers.BuildXmlDocs(signature.Parameters, signature.Description, null, paramHash);`
`43`	`43`	`EnclosingType = enclosingType;`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,9 @@ public class MethodProvider`
`15`	`15`	`public MethodSignature Signature { get; private set; }`
`16`	`16`	`public MethodBodyStatement? BodyStatements { get; private set;}`
`17`	`17`	`public ValueExpression? BodyExpression { get; private set;}`
`18`		`- public XmlDocProvider? XmlDocs { get; private set;}`
	`18`	`+`
	`19`	`+ public XmlDocProvider? XmlDocs => _xmlDocs ??= BuildXmlDocs();`
	`20`	`+ private XmlDocProvider? _xmlDocs;`
`19`	`21`
`20`	`22`	`public TypeProvider EnclosingType { get; }`
`21`	`23`
`@@ -37,9 +39,9 @@ public MethodProvider(MethodSignature signature, MethodBodyStatement bodyStateme`
`37`	`39`	`{`
`38`	`40`	`Signature = signature;`
`39`	`41`	`bool skipParamValidation = !signature.Modifiers.HasFlag(MethodSignatureModifiers.Public);`
`40`		`- var paramHash = MethodProviderHelpers.GetParamhash(signature.Parameters, skipParamValidation);`
	`42`	`+ var paramHash = MethodProviderHelpers.GetParamHash(signature.Parameters, skipParamValidation);`
`41`	`43`	`BodyStatements = MethodProviderHelpers.GetBodyStatementWithValidation(signature.Parameters, bodyStatements, paramHash);`
`42`		`- XmlDocs = xmlDocProvider ?? MethodProviderHelpers.BuildXmlDocs(signature.Parameters, signature.Description, signature.ReturnDescription, paramHash);`
	`44`	`+ _xmlDocs = xmlDocProvider;`
`43`	`45`	`EnclosingType = enclosingType;`
`44`	`46`	`}`
`45`	`47`
`@@ -54,10 +56,23 @@ public MethodProvider(MethodSignature signature, ValueExpression bodyExpression,`
`54`	`56`	`{`
`55`	`57`	`Signature = signature;`
`56`	`58`	`BodyExpression = bodyExpression;`
`57`		`- XmlDocs = xmlDocProvider ?? MethodProviderHelpers.BuildXmlDocs(signature.Parameters, signature.Description, signature.ReturnDescription, null);`
	`59`	`+ _xmlDocs = xmlDocProvider;`
`58`	`60`	`EnclosingType = enclosingType;`
`59`	`61`	`}`
`60`	`62`
	`63`	`+ private XmlDocProvider? BuildXmlDocs()`
	`64`	`+ {`
	`65`	`+ return MethodProviderHelpers.BuildXmlDocs(`
	`66`	`+ Signature.Parameters,`
	`67`	`+ Signature.Description,`
	`68`	`+ Signature.ReturnDescription,`
	`69`	`+ BodyStatements != null ?`
	`70`	`+ MethodProviderHelpers.GetParamHash(`
	`71`	`+ Signature.Parameters,`
	`72`	`+ !Signature.Modifiers.HasFlag(MethodSignatureModifiers.Public)) :`
	`73`	`+ null);`
	`74`	`+ }`
	`75`	`+`
`61`	`76`	`public void Update(`
`62`	`77`	`MethodSignature? signature = null,`
`63`	`78`	`MethodBodyStatement? bodyStatements = null,`
`@@ -67,6 +82,8 @@ public void Update(`
`67`	`82`	`if (signature != null)`
`68`	`83`	`{`
`69`	`84`	`Signature = signature;`
	`85`	`+ // rebuild the XML docs if the signature changes`
	`86`	`+ _xmlDocs = BuildXmlDocs();`
`70`	`87`	`}`
`71`	`88`	`if (bodyStatements != null)`
`72`	`89`	`{`
`@@ -80,7 +97,7 @@ public void Update(`
`80`	`97`	`}`
`81`	`98`	`if (xmlDocProvider != null)`
`82`	`99`	`{`
`83`		`- XmlDocs = xmlDocProvider;`
	`100`	`+ _xmlDocs = xmlDocProvider;`
`84`	`101`	`}`
`85`	`102`	`}`
`86`	`103`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ namespace Microsoft.TypeSpec.Generator`
`12`	`12`	`{`
`13`	`13`	`internal static class MethodProviderHelpers`
`14`	`14`	`{`
`15`		`- public static Dictionary<ParameterValidationType, List<ParameterProvider>>? GetParamhash(IEnumerable<ParameterProvider> parameters, bool skipParamValidation)`
	`15`	`+ public static Dictionary<ParameterValidationType, List<ParameterProvider>>? GetParamHash(IEnumerable<ParameterProvider> parameters, bool skipParamValidation)`
`16`	`16`	`{`
`17`	`17`	`Dictionary<ParameterValidationType, List<ParameterProvider>>? paramHash = null;`
`18`	`18`	`if (!skipParamValidation)`