Handle langword for see elements

Handle `<see langword="" />` references in XML documentation as inline code.

Contributes to #61042.

Author: martincostello

src/OpenApi/gen/XmlComments/XmlComment.cs

@@ -35,8 +35,11 @@ private XmlComment(Compilation compilation, string xml)
         // Transform triple slash comment
         var doc = XDocument.Parse(xml, LoadOptions.PreserveWhitespace | LoadOptions.SetLineInfo);
 
-        ResolveCrefLink(compilation, doc, $"//{DocumentationCommentXmlNames.SeeAlsoElementName}[@cref]");
-        ResolveCrefLink(compilation, doc, $"//{DocumentationCommentXmlNames.SeeElementName}[@cref]");
+        ResolveCrefLink(compilation, doc, DocumentationCommentXmlNames.SeeAlsoElementName);
+        ResolveCrefLink(compilation, doc, DocumentationCommentXmlNames.SeeElementName);
+
+        ResolveLangKeyword(doc, DocumentationCommentXmlNames.SeeElementName);
+
         // Resolve <list> and <item> tags into bullets
         ResolveListTags(doc);
         // Resolve <code> tags into code blocks
@@ -171,18 +174,20 @@ private static void ResolveParaTags(XDocument document)
     /// </summary>
     /// <param name="compilation">The compilation to resolve type symbol declarations from.</param>
     /// <param name="node">The target node to process crefs in.</param>
-    /// <param name="nodeSelector">The node type to process crefs for, can be `see` or `seealso`.</param>
-    private static void ResolveCrefLink(Compilation compilation, XNode node, string nodeSelector)
+    /// <param name="elementName">The node type to process crefs for, can be `see` or `seealso`.</param>
+    private static void ResolveCrefLink(Compilation compilation, XNode node, string elementName)
     {
-        if (node == null || string.IsNullOrEmpty(nodeSelector))
+        if (node == null || string.IsNullOrEmpty(elementName))
         {
             return;
         }
 
-        var nodes = node.XPathSelectElements(nodeSelector + "[@cref]").ToArray();
+        var attributeName = DocumentationCommentXmlNames.CrefAttributeName;
+
+        var nodes = node.XPathSelectElements($"//{elementName}[@{attributeName}]").ToArray();
         foreach (var item in nodes)
         {
-            var cref = item.Attribute(DocumentationCommentXmlNames.CrefAttributeName).Value;
+            var cref = item.Attribute(attributeName).Value;
             if (string.IsNullOrEmpty(cref))
             {
                 continue;
@@ -197,6 +202,35 @@ private static void ResolveCrefLink(Compilation compilation, XNode node, string
         }
     }
 
+    /// <summary>
+    /// Resolves the links in the XML documentation into type names.
+    /// </summary>
+    /// <param name="node">The target node to process crefs in.</param>
+    /// <param name="elementName">The node type to process crefs for, can be `see` or `seealso`.</param>
+    private static void ResolveLangKeyword(XNode node, string elementName)
+    {
+        if (node == null || string.IsNullOrEmpty(elementName))
+        {
+            return;
+        }
+
+        var attributeName = DocumentationCommentXmlNames.LangwordAttributeName;
+
+        var nodes = node.XPathSelectElements($"//{elementName}[@{attributeName}]").ToArray();
+        foreach (var item in nodes)
+        {
+            var langword = item.Attribute(attributeName).Value;
+            if (string.IsNullOrEmpty(langword))
+            {
+                continue;
+            }
+
+            // TODO Is this the right thing to do? For example C# would get `true`, `false`, `null`
+            // but VB would get `True`, `False`, `Nothing`. They should emit in neutral OpenAPI terms?
+            item.ReplaceWith(new XText($"`{langword}`"));
+        }
+    }
+
     private static IEnumerable<string?> GetMultipleExampleNodes(XPathNavigator navigator, string selector)
     {
         var iterator = navigator.Select(selector);

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs

@@ -1,8 +1,6 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-using System.Globalization;
-using System.Text.Json.Nodes;
 using Microsoft.OpenApi.Models;
 
 namespace Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests;
@@ -354,6 +352,39 @@ public static T GetGenericValue<T>(T para)
         return para;
     }
 }
+
+/// <summary>
+/// A class that implements the <see cref="IDisposable"/> interface.
+/// </summary>
+public class DisposableType : IDisposable
+{
+    /// <summary>
+    /// Finalizes an instance of the <see cref="DisposableType"/> class.
+    /// </summary>
+    ~DisposableType()
+    {
+        Dispose(false);
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    /// <summary>
+    /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+    /// </summary>
+    /// <param name="disposing">
+    /// <see langword="true" /> to release both managed and unmanaged resources;
+    /// <see langword="false" /> to release only unmanaged resources.
+    /// </param>
+    protected virtual void Dispose(bool disposing)
+    {
+        // No-op
+    }
+}
 """;
         var generator = new XmlCommentGenerator();
         await SnapshotTestHelper.Verify(source, generator, out var compilation);

src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs

@@ -259,7 +259,8 @@ type as a cref attribute.
 In generic classes and methods, you'll often want to reference the
 generic type, or the type parameter.", null, null, false, null, null, null));
             _cache.Add(new MemberKey(typeof(global::ParamsAndParamRefs), MemberType.Type, null, null, []), new XmlComment(@"This shows examples of typeparamref and typeparam tags", null, null, null, null, false, null, null, null));
-            _cache.Add(new MemberKey(typeof(global::ExampleClass), MemberType.Property, "Label", null, []), new XmlComment(null, null, @"    The string? ExampleClass.Label is a <see langword=""string"" />
+            _cache.Add(new MemberKey(typeof(global::DisposableType), MemberType.Type, null, null, []), new XmlComment(@"A class that implements the IDisposable interface.", null, null, null, null, false, null, null, null));
+            _cache.Add(new MemberKey(typeof(global::ExampleClass), MemberType.Property, "Label", null, []), new XmlComment(null, null, @"    The string? ExampleClass.Label is a `string`
     that you use for a label.
     Note that there isn't a way to provide a ""cref"" to
 each accessor, only to the property itself.", null, @"The `Label` property represents a label
@@ -289,6 +290,10 @@ that implement this interface when the
 method as a cref attribute.
 The parameter and return value are both of an arbitrary type,
 T", null, null, false, null, null, null));
+            _cache.Add(new MemberKey(typeof(global::DisposableType), MemberType.Method, "Finalize", typeof(void), []), new XmlComment(@"Finalizes an instance of the DisposableType class.", null, null, null, null, false, null, null, null));
+            _cache.Add(new MemberKey(typeof(global::DisposableType), MemberType.Method, "Dispose", typeof(void), []), new XmlComment(null, null, null, null, null, false, null, null, null));
+            _cache.Add(new MemberKey(typeof(global::DisposableType), MemberType.Method, "Dispose", typeof(void), [typeof(global::System.Boolean)]), new XmlComment(@"Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.", null, null, null, null, false, null, [new XmlParameterComment(@"disposing", @"`true` to release both managed and unmanaged resources;
+`false` to release only unmanaged resources.", null, false)], null));
 
             return _cache;
         }