feat: calculate internal cross-reference URL without xrefmap (dotnet#…

…8588)
ErpNetDocs · Jun 28, 2024 · 3e70513 · 3e70513
1 parent 2ac0997
commit 3e70513
Show file tree

Hide file tree

Showing 80 changed files with 413 additions and 188 deletions.
diff --git a/src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs b/src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs
@@ -142,11 +142,13 @@ await LoadCompilationFromProject(project.AbsolutePath) is { } compilation)
         var projectMetadataList = new List<MetadataItem>();
         var extensionMethods = assemblies.SelectMany(assembly => assembly.Item1.FindExtensionMethods()).ToArray();
         var filter = new SymbolFilter(_config, _options);
+        var allAssemblies = new HashSet<IAssemblySymbol>(assemblies.Select(a => a.Item1), SymbolEqualityComparer.Default);
 
         foreach (var (assembly, compilation) in assemblies)
         {
             Logger.LogInfo($"Processing {assembly.Name}");
-            var projectMetadata = assembly.Accept(new SymbolVisitorAdapter(compilation, new(compilation), _config, filter, extensionMethods));
+            var projectMetadata = assembly.Accept(new SymbolVisitorAdapter(
+                compilation, new(compilation, _config.MemberLayout, allAssemblies), _config, filter, extensionMethods));
 
             if (projectMetadata != null)
                 projectMetadataList.Add(projectMetadata);

diff --git a/src/Microsoft.DocAsCode.Dotnet/SymbolFormatter.cs b/src/Microsoft.DocAsCode.Dotnet/SymbolFormatter.cs
@@ -108,7 +108,8 @@ public static ImmutableArray<SymbolDisplayPart> GetSyntaxParts(ISymbol symbol, S
         }
     }
 
-    public static List<LinkItem> ToLinkItems(this ImmutableArray<SymbolDisplayPart> parts, Compilation compilation, SyntaxLanguage language, bool overload)
+    public static List<LinkItem> ToLinkItems(this ImmutableArray<SymbolDisplayPart> parts,
+        Compilation compilation, MemberLayout memberLayout, HashSet<IAssemblySymbol> allAssemblies, bool overload)
     {
         var result = new List<LinkItem>();
         foreach (var part in parts)
@@ -133,7 +134,7 @@ LinkItem ToLinkItem(SymbolDisplayPart part)
             {
                 Name = overload ? VisitorHelper.GetOverloadId(symbol) : VisitorHelper.GetId(symbol),
                 DisplayName = part.ToString(),
-                Href = SymbolUrlResolver.GetSymbolUrl(symbol, compilation),
+                Href = SymbolUrlResolver.GetSymbolUrl(symbol, compilation, memberLayout, allAssemblies),
                 IsExternalPath = symbol.IsExtern || symbol.DeclaringSyntaxReferences.Length == 0,
             };
         }

diff --git a/src/Microsoft.DocAsCode.Dotnet/SymbolHelper.cs b/src/Microsoft.DocAsCode.Dotnet/SymbolHelper.cs
@@ -9,7 +9,7 @@ internal static class SymbolHelper
     public static MetadataItem? GenerateMetadataItem(this IAssemblySymbol assembly, Compilation compilation, ExtractMetadataConfig? config = null, DotnetApiOptions? options = null, IMethodSymbol[]? extensionMethods = null)
     {
         config ??= new();
-        return assembly.Accept(new SymbolVisitorAdapter(compilation, new(compilation), config, new(config, options ?? new()), extensionMethods));
+        return assembly.Accept(new SymbolVisitorAdapter(compilation, new(compilation, MemberLayout.SamePage, new(new[] { assembly }, SymbolEqualityComparer.Default)), config, new(config, options ?? new()), extensionMethods));
     }
 
     public static bool IsInstanceInterfaceMember(this ISymbol symbol)

diff --git a/src/Microsoft.DocAsCode.Dotnet/SymbolUrlResolver.cs b/src/Microsoft.DocAsCode.Dotnet/SymbolUrlResolver.cs
@@ -1,14 +1,40 @@
-using Microsoft.CodeAnalysis;
+using System.Text.RegularExpressions;
+using Microsoft.CodeAnalysis;
 
 #nullable enable
 
 namespace Microsoft.DocAsCode.Dotnet;
 
 internal static partial class SymbolUrlResolver
 {
-    public static string? GetSymbolUrl(ISymbol symbol, Compilation compilation)
+    public static string? GetSymbolUrl(ISymbol symbol, Compilation compilation, MemberLayout memberLayout, HashSet<IAssemblySymbol> allAssemblies)
     {
-        return GetMicrosoftLearnUrl(symbol)
+        return GetDocfxUrl(symbol, memberLayout, allAssemblies)
+            ?? GetMicrosoftLearnUrl(symbol)
             ?? GetPdbSourceLinkUrl(compilation, symbol);
     }
+
+    internal static string? GetDocfxUrl(ISymbol symbol, MemberLayout memberLayout, HashSet<IAssemblySymbol> allAssemblies)
+    {
+        if (symbol.ContainingAssembly is null || !allAssemblies.Contains(symbol.ContainingAssembly))
+            return null;
+
+        var commentId = symbol.GetDocumentationCommentId();
+        if (commentId is null)
+            return null;
+
+        var parts = commentId.Split(':');
+        var type = parts[0];
+        var uid = parts[1];
+
+        return type switch
+        {
+            "!" => null,
+            "N" or "T" => $"{uid.Replace('`', '-')}.html",
+            "M" or "F" or "P" or "E" => memberLayout is MemberLayout.SeparatePages && !symbol.IsEnumMember()
+                ? $"{VisitorHelper.GetId(symbol).Replace('`', '-')}.html"
+                : $"{VisitorHelper.GetId(symbol.ContainingType).Replace('`', '-')}.html#{Regex.Replace(uid, @"/\W/", "_")}",
+            _ => throw new NotSupportedException($"Unknown comment ID format '{type}"),
+        };
+    }
 }
diff --git a/src/Microsoft.DocAsCode.Dotnet/Visitors/YamlModelGenerator.cs b/src/Microsoft.DocAsCode.Dotnet/Visitors/YamlModelGenerator.cs
@@ -9,10 +9,14 @@ namespace Microsoft.DocAsCode.Dotnet;
 internal class YamlModelGenerator
 {
     private readonly Compilation _compilation;
+    private readonly MemberLayout _memberLayout;
+    private readonly HashSet<IAssemblySymbol> _allAssemblies;
 
-    public YamlModelGenerator(Compilation compilation)
+    public YamlModelGenerator(Compilation compilation, MemberLayout memberLayout, HashSet<IAssemblySymbol> allAssemblies)
     {
         _compilation = compilation;
+        _memberLayout = memberLayout;
+        _allAssemblies = allAssemblies;
     }
 
     public void DefaultVisit(ISymbol symbol, MetadataItem item)
@@ -35,9 +39,9 @@ public void GenerateReference(ISymbol symbol, ReferenceItem reference, bool asOv
         if (!reference.QualifiedNameParts.ContainsKey(SyntaxLanguage.CSharp))
             reference.QualifiedNameParts.Add(SyntaxLanguage.CSharp, new());
 
-        reference.NameParts[SyntaxLanguage.CSharp] = SymbolFormatter.GetNameParts(symbol, SyntaxLanguage.CSharp, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, SyntaxLanguage.CSharp, asOverload);
-        reference.NameWithTypeParts[SyntaxLanguage.CSharp] = SymbolFormatter.GetNameWithTypeParts(symbol, SyntaxLanguage.CSharp, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, SyntaxLanguage.CSharp, asOverload);
-        reference.QualifiedNameParts[SyntaxLanguage.CSharp] = SymbolFormatter.GetQualifiedNameParts(symbol, SyntaxLanguage.CSharp, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, SyntaxLanguage.CSharp, asOverload);
+        reference.NameParts[SyntaxLanguage.CSharp] = SymbolFormatter.GetNameParts(symbol, SyntaxLanguage.CSharp, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, _memberLayout, _allAssemblies, asOverload);
+        reference.NameWithTypeParts[SyntaxLanguage.CSharp] = SymbolFormatter.GetNameWithTypeParts(symbol, SyntaxLanguage.CSharp, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, _memberLayout, _allAssemblies, asOverload);
+        reference.QualifiedNameParts[SyntaxLanguage.CSharp] = SymbolFormatter.GetQualifiedNameParts(symbol, SyntaxLanguage.CSharp, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, _memberLayout, _allAssemblies, asOverload);
 
         if (!reference.NameParts.ContainsKey(SyntaxLanguage.VB))
             reference.NameParts.Add(SyntaxLanguage.VB, new());
@@ -46,9 +50,9 @@ public void GenerateReference(ISymbol symbol, ReferenceItem reference, bool asOv
         if (!reference.QualifiedNameParts.ContainsKey(SyntaxLanguage.VB))
             reference.QualifiedNameParts.Add(SyntaxLanguage.VB, new());
 
-        reference.NameParts[SyntaxLanguage.VB] = SymbolFormatter.GetNameParts(symbol, SyntaxLanguage.VB, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, SyntaxLanguage.VB, asOverload);
-        reference.NameWithTypeParts[SyntaxLanguage.VB] = SymbolFormatter.GetNameWithTypeParts(symbol, SyntaxLanguage.VB, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, SyntaxLanguage.VB, asOverload);
-        reference.QualifiedNameParts[SyntaxLanguage.VB] = SymbolFormatter.GetQualifiedNameParts(symbol, SyntaxLanguage.VB, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, SyntaxLanguage.VB, asOverload);
+        reference.NameParts[SyntaxLanguage.VB] = SymbolFormatter.GetNameParts(symbol, SyntaxLanguage.VB, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, _memberLayout, _allAssemblies, asOverload);
+        reference.NameWithTypeParts[SyntaxLanguage.VB] = SymbolFormatter.GetNameWithTypeParts(symbol, SyntaxLanguage.VB, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, _memberLayout, _allAssemblies, asOverload);
+        reference.QualifiedNameParts[SyntaxLanguage.VB] = SymbolFormatter.GetQualifiedNameParts(symbol, SyntaxLanguage.VB, nullableReferenceType: false, asOverload).ToLinkItems(_compilation, _memberLayout, _allAssemblies, asOverload);
     }
 
     public void GenerateSyntax(ISymbol symbol, SyntaxDetail syntax, SymbolFilter filter)

diff --git a/...Tests/SamplesTest.CSharp/api/CSharp10.ConstantInterpolatedStrings.html.view.verified.json b/...Tests/SamplesTest.CSharp/api/CSharp10.ConstantInterpolatedStrings.html.view.verified.json
@@ -6,6 +6,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -516,6 +517,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",

diff --git a/test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.Issue7737.html.view.verified.json b/test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.Issue7737.html.view.verified.json
@@ -6,6 +6,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -244,6 +245,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",

diff --git a/...s/SamplesTest.CSharp/api/CSharp10.ParameterlessStructConstructors.html.view.verified.json b/...s/SamplesTest.CSharp/api/CSharp10.ParameterlessStructConstructors.html.view.verified.json
@@ -6,6 +6,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -753,6 +754,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",

diff --git a/...apshot.Tests/SamplesTest.CSharp/api/CSharp10.ReadOnlyRecordStruct.html.view.verified.json b/...apshot.Tests/SamplesTest.CSharp/api/CSharp10.ReadOnlyRecordStruct.html.view.verified.json
@@ -6,6 +6,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -931,6 +932,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -1023,11 +1025,11 @@
       "specName": [
         {
           "lang": "csharp",
-          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>&lt;<xref uid=\"CSharp10.ReadOnlyRecordStruct\" text=\"ReadOnlyRecordStruct\"/>&gt;"
+          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>&lt;<a class=\"xref\" href=\"CSharp10.ReadOnlyRecordStruct.html\">ReadOnlyRecordStruct</a>&gt;"
         },
         {
           "lang": "vb",
-          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>(Of <xref uid=\"CSharp10.ReadOnlyRecordStruct\" text=\"ReadOnlyRecordStruct\"/>)"
+          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>(Of <a class=\"xref\" href=\"CSharp10.ReadOnlyRecordStruct.html\">ReadOnlyRecordStruct</a>)"
         }
       ]
     }

diff --git a/.../docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.RecordClass.html.view.verified.json b/.../docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.RecordClass.html.view.verified.json
@@ -6,6 +6,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -705,6 +706,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -849,11 +851,11 @@
       "specName": [
         {
           "lang": "csharp",
-          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>&lt;<xref uid=\"CSharp10.RecordClass\" text=\"RecordClass\"/>&gt;"
+          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>&lt;<a class=\"xref\" href=\"CSharp10.RecordClass.html\">RecordClass</a>&gt;"
         },
         {
           "lang": "vb",
-          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>(Of <xref uid=\"CSharp10.RecordClass\" text=\"RecordClass\"/>)"
+          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>(Of <a class=\"xref\" href=\"CSharp10.RecordClass.html\">RecordClass</a>)"
         }
       ]
     }

diff --git a/...docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.RecordStruct.html.view.verified.json b/...docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.RecordStruct.html.view.verified.json
@@ -6,6 +6,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -705,6 +706,7 @@
     "uid": "CSharp10",
     "isEii": false,
     "isExtensionMethod": false,
+    "href": "CSharp10.html",
     "name": [
       {
         "lang": "csharp",
@@ -797,11 +799,11 @@
       "specName": [
         {
           "lang": "csharp",
-          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>&lt;<xref uid=\"CSharp10.RecordStruct\" text=\"RecordStruct\"/>&gt;"
+          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>&lt;<a class=\"xref\" href=\"CSharp10.RecordStruct.html\">RecordStruct</a>&gt;"
         },
         {
           "lang": "vb",
-          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>(Of <xref uid=\"CSharp10.RecordStruct\" text=\"RecordStruct\"/>)"
+          "value": "<a class=\"xref\" href=\"https://learn.microsoft.com/dotnet/api/system.iequatable-1\">IEquatable</a>(Of <a class=\"xref\" href=\"CSharp10.RecordStruct.html\">RecordStruct</a>)"
         }
       ]
     }

diff --git a/test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.html.view.verified.json b/test/docfx.Snapshot.Tests/SamplesTest.CSharp/api/CSharp10.html.view.verified.json
@@ -11,6 +11,7 @@
         {
           "uid": "CSharp10.ConstantInterpolatedStrings",
           "isExtensionMethod": false,
+          "href": "CSharp10.ConstantInterpolatedStrings.html",
           "name": [
             {
               "lang": "csharp",
@@ -71,6 +72,7 @@
         {
           "uid": "CSharp10.Issue7737",
           "isExtensionMethod": false,
+          "href": "CSharp10.Issue7737.html",
           "name": [
             {
               "lang": "csharp",
@@ -131,6 +133,7 @@
         {
           "uid": "CSharp10.RecordClass",
           "isExtensionMethod": false,
+          "href": "CSharp10.RecordClass.html",
           "name": [
             {
               "lang": "csharp",
@@ -198,6 +201,7 @@
         {
           "uid": "CSharp10.ParameterlessStructConstructors",
           "isExtensionMethod": false,
+          "href": "CSharp10.ParameterlessStructConstructors.html",
           "name": [
             {
               "lang": "csharp",
@@ -258,6 +262,7 @@
         {
           "uid": "CSharp10.ReadOnlyRecordStruct",
           "isExtensionMethod": false,
+          "href": "CSharp10.ReadOnlyRecordStruct.html",
           "name": [
             {
               "lang": "csharp",
@@ -318,6 +323,7 @@
         {
           "uid": "CSharp10.RecordStruct",
           "isExtensionMethod": false,
+          "href": "CSharp10.RecordStruct.html",
           "name": [
             {
               "lang": "csharp",