Extensions: xml docs (#78365)

jcouv · web-flow · commit 9041fb0b9d39 · 2025-04-30T17:16:36.000Z
diff --git a/src/Compilers/CSharp/Portable/Binder/BinderFactory.BinderFactoryVisitor.cs b/src/Compilers/CSharp/Portable/Binder/BinderFactory.BinderFactoryVisitor.cs
@@ -1213,7 +1213,7 @@ public override Binder VisitXmlNameAttribute(XmlNameAttributeSyntax parent)
                         {
                             case XmlNameAttributeElementKind.Parameter:
                             case XmlNameAttributeElementKind.ParameterReference:
-                                result = GetParameterNameAttributeValueBinder(memberSyntax, result);
+                                result = GetParameterNameAttributeValueBinder(memberSyntax, isParamRef: elementKind == XmlNameAttributeElementKind.ParameterReference, nextBinder: result);
                                 break;
                             case XmlNameAttributeElementKind.TypeParameter:
                                 result = GetTypeParameterNameAttributeValueBinder(memberSyntax, includeContainingSymbols: false, nextBinder: result);
@@ -1234,16 +1234,28 @@ public override Binder VisitXmlNameAttribute(XmlNameAttributeSyntax parent)
             /// We're in a &lt;param&gt; or &lt;paramref&gt; element, so we want a binder that can see
             /// the parameters of the associated member and nothing else.
             /// </summary>
-            private Binder GetParameterNameAttributeValueBinder(MemberDeclarationSyntax memberSyntax, Binder nextBinder)
+            private Binder GetParameterNameAttributeValueBinder(MemberDeclarationSyntax memberSyntax, bool isParamRef, Binder nextBinder)
             {
                 if (memberSyntax is BaseMethodDeclarationSyntax { ParameterList: { ParameterCount: > 0 } } baseMethodDeclSyntax)
                 {
                     Binder outerBinder = VisitCore(memberSyntax.Parent);
                     MethodSymbol method = GetMethodSymbol(baseMethodDeclSyntax, outerBinder);
+
+                    if (isParamRef && method.TryGetInstanceExtensionParameter(out var _))
+                    {
+                        nextBinder = new WithExtensionParameterBinder(method.ContainingType, nextBinder);
+                    }
+
                     return new WithParametersBinder(method.Parameters, nextBinder);
                 }
-
-                if (memberSyntax is TypeDeclarationSyntax { ParameterList: { ParameterCount: > 0 } } typeDeclaration)
+                else if (memberSyntax is ExtensionDeclarationSyntax extensionDeclaration)
+                {
+                    Binder outerBinder = VisitCore(memberSyntax);
+                    SourceNamedTypeSymbol type = ((NamespaceOrTypeSymbol)outerBinder.ContainingMemberOrLambda).GetSourceTypeMember((TypeDeclarationSyntax)memberSyntax);
+                    Debug.Assert(type.IsExtension);
+                    return new WithExtensionParameterBinder(type, nextBinder);
+                }
+                else if (memberSyntax is TypeDeclarationSyntax { ParameterList: { ParameterCount: > 0 } } typeDeclaration)
                 {
                     _ = typeDeclaration.ParameterList;
                     Binder outerBinder = VisitCore(memberSyntax);
@@ -1268,6 +1280,11 @@ private Binder GetParameterNameAttributeValueBinder(MemberDeclarationSyntax memb
 
                     ImmutableArray<ParameterSymbol> parameters = property.Parameters;
 
+                    if (isParamRef && property.TryGetInstanceExtensionParameter(out var _))
+                    {
+                        nextBinder = new WithExtensionParameterBinder(property.ContainingType, nextBinder);
+                    }
+
                     // BREAK: Dev11 also allows "value" for readonly properties, but that doesn't
                     // make sense and we don't have a symbol.
                     if ((object)property.SetMethod != null)
@@ -1278,8 +1295,10 @@ private Binder GetParameterNameAttributeValueBinder(MemberDeclarationSyntax memb
 
                     if (parameters.Any())
                     {
-                        return new WithParametersBinder(parameters, nextBinder);
+                        nextBinder = new WithParametersBinder(parameters, nextBinder);
                     }
+
+                    return nextBinder;
                 }
                 else if (memberKind == SyntaxKind.DelegateDeclaration)
                 {
diff --git a/src/Compilers/CSharp/Portable/Compiler/DocumentationCommentCompiler.cs b/src/Compilers/CSharp/Portable/Compiler/DocumentationCommentCompiler.cs
@@ -237,6 +237,47 @@ public override void VisitNamedType(NamedTypeSymbol symbol)
         }
 
 #nullable enable
+        public override void VisitMethod(MethodSymbol symbol)
+        {
+            if (symbol is SourceExtensionImplementationMethodSymbol implementation)
+            {
+                MethodSymbol underlyingMethod = implementation.UnderlyingMethod;
+                Symbol symbolForDocComment = underlyingMethod.IsAccessor()
+                    ? underlyingMethod.AssociatedSymbol
+                    : underlyingMethod;
+
+                if (!hasDocumentationTrivia(symbolForDocComment))
+                {
+                    return;
+                }
+
+                WriteLine("<member name=\"{0}\">", symbol.GetDocumentationCommentId());
+                Indent();
+                WriteLine("<inheritdoc cref=\"{0}\"/>", symbolForDocComment.GetDocumentationCommentId());
+                Unindent();
+                WriteLine("</member>");
+                return;
+            }
+
+            base.VisitMethod(symbol);
+            return;
+
+            static bool hasDocumentationTrivia(Symbol symbol)
+            {
+                foreach (SyntaxReference reference in symbol.DeclaringSyntaxReferences)
+                {
+                    foreach (var trivia in reference.GetSyntax().GetLeadingTrivia())
+                    {
+                        if (trivia.IsDocumentationCommentTrivia)
+                        {
+                            return true;
+                        }
+                    }
+                }
+
+                return false;
+            }
+        }
 
         /// <summary>
         /// Compile documentation comments on the symbol and write them to the stream if one is provided.
diff --git a/src/Compilers/CSharp/Portable/DocumentationComments/DocumentationCommentIDVisitor.PartVisitor.cs b/src/Compilers/CSharp/Portable/DocumentationComments/DocumentationCommentIDVisitor.PartVisitor.cs
@@ -181,7 +181,7 @@ public override object VisitNamedType(NamedTypeSymbol symbol, StringBuilder buil
                     builder.Append('.');
                 }
 
-                builder.Append(symbol.Name);
+                builder.Append(symbol.IsExtension ? symbol.ExtensionName : symbol.Name);
 
                 if (symbol.Arity != 0)
                 {
diff --git a/src/Compilers/CSharp/Portable/Symbols/Extensions/SourceExtensionImplementationMethodSymbol.cs b/src/Compilers/CSharp/Portable/Symbols/Extensions/SourceExtensionImplementationMethodSymbol.cs
@@ -4,13 +4,17 @@
 
 using System.Collections.Immutable;
 using System.Diagnostics;
+using System.Globalization;
+using System.Threading;
 using Microsoft.CodeAnalysis.CSharp.Emit;
 using Microsoft.CodeAnalysis.PooledObjects;
 
 namespace Microsoft.CodeAnalysis.CSharp.Symbols
 {
     internal sealed class SourceExtensionImplementationMethodSymbol : RewrittenMethodSymbol // Tracked by https://github.com/dotnet/roslyn/issues/76130 : Do we need to implement ISynthesizedMethodBodyImplementationSymbol?
     {
+        private string? lazyDocComment;
+
         public SourceExtensionImplementationMethodSymbol(MethodSymbol sourceMethod)
             : base(sourceMethod, TypeMap.Empty, sourceMethod.ContainingType.TypeParameters.Concat(sourceMethod.TypeParameters))
         {
@@ -57,8 +61,6 @@ internal override int ParameterCount
         public sealed override DllImportData? GetDllImportData() => null;
         internal sealed override bool IsExternal => false;
 
-        // Tracked by https://github.com/dotnet/roslyn/issues/76130 : How doc comments are supposed to work? GetDocumentationCommentXml
-
         internal sealed override bool IsDeclaredReadOnly => false;
 
         public sealed override Symbol ContainingSymbol => _originalMethod.ContainingType.ContainingSymbol;
@@ -131,6 +133,20 @@ internal override int TryGetOverloadResolutionPriority()
             return UnderlyingMethod.TryGetOverloadResolutionPriority();
         }
 
+        public override string GetDocumentationCommentXml(CultureInfo? preferredCulture = null, bool expandIncludes = false, CancellationToken cancellationToken = default)
+        {
+            // Neither the culture nor the expandIncludes affect the XML for extension implementation methods.
+            string result = SourceDocumentationCommentUtils.GetAndCacheDocumentationComment(this, expandIncludes: false, ref lazyDocComment);
+
+#if DEBUG
+            string? ignored = null;
+            string withIncludes = SourceDocumentationCommentUtils.GetAndCacheDocumentationComment(this, expandIncludes: true, lazyXmlText: ref ignored);
+            Debug.Assert(string.Equals(result, withIncludes, System.StringComparison.Ordinal));
+#endif
+
+            return result;
+        }
+
         private sealed class ExtensionMetadataMethodParameterSymbol : RewrittenMethodParameterSymbol
         {
             public ExtensionMetadataMethodParameterSymbol(SourceExtensionImplementationMethodSymbol containingMethod, ParameterSymbol sourceParameter) :
diff --git a/src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests.cs b/src/Compilers/CSharp/Test/Emit3/Semantics/ExtensionTests.cs

Original file line number	Diff line number	Diff line change
`@@ -181,7 +181,7 @@ public override object VisitNamedType(NamedTypeSymbol symbol, StringBuilder buil`
`181`	`181`	`builder.Append('.');`
`182`	`182`	`}`
`183`	`183`
`184`		`- builder.Append(symbol.Name);`
	`184`	`+ builder.Append(symbol.IsExtension ? symbol.ExtensionName : symbol.Name);`
`185`	`185`
`186`	`186`	`if (symbol.Arity != 0)`
`187`	`187`	`{`