diff --git a/src/OpenApi/gen/XmlComments/XmlComment.cs b/src/OpenApi/gen/XmlComments/XmlComment.cs index be47fa913d82..f17618404ad4 100644 --- a/src/OpenApi/gen/XmlComments/XmlComment.cs +++ b/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 and tags into bullets ResolveListTags(doc); // Resolve tags into code blocks @@ -171,18 +174,20 @@ private static void ResolveParaTags(XDocument document) /// /// The compilation to resolve type symbol declarations from. /// The target node to process crefs in. - /// The node type to process crefs for, can be `see` or `seealso`. - private static void ResolveCrefLink(Compilation compilation, XNode node, string nodeSelector) + /// The node type to process crefs for, can be `see` or `seealso`. + 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 } } + /// + /// Resolves the links in the XML documentation into type names. + /// + /// The target node to process crefs in. + /// The node type to process crefs for, can be `see` or `seealso`. + 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 GetMultipleExampleNodes(XPathNavigator navigator, string selector) { var iterator = navigator.Select(selector); diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs index d3749372ad4a..892e90b8b7be 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/CompletenessTests.cs +++ b/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 para) return para; } } + +/// +/// A class that implements the interface. +/// +public class DisposableType : IDisposable +{ + /// + /// Finalizes an instance of the class. + /// + ~DisposableType() + { + Dispose(false); + } + + /// + public void Dispose() + { + Dispose(true); + GC.SuppressFinalize(this); + } + + /// + /// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. + /// + /// + /// to release both managed and unmanaged resources; + /// to release only unmanaged resources. + /// + protected virtual void Dispose(bool disposing) + { + // No-op + } +} """; var generator = new XmlCommentGenerator(); await SnapshotTestHelper.Verify(source, generator, out var compilation); diff --git a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs b/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs index d2cfab1740bc..cb51146ccf45 100644 --- a/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.SourceGenerators.Tests/snapshots/CompletenessTests.SupportsAllXmlTagsOnSchemas#OpenApiXmlCommentSupport.generated.verified.cs +++ b/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 + _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; }