feat: support <inheritdoc> tag

dotnet · Apr 3, 2023 · 23d3838 · 23d3838
1 parent 3c87326
commit 23d3838
Show file tree

Hide file tree

Showing 10 changed files with 21 additions and 290 deletions.
diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -8,6 +8,7 @@
     <PackageVersion Include="CommandLineParser" Version="1.9.71" />
     <PackageVersion Include="HtmlAgilityPack" Version="1.11.46" />
     <PackageVersion Include="ICSharpCode.Decompiler" Version="8.0.0.7246-preview3" />
+    <PackageVersion Include="IgnoresAccessChecksToGenerator" Version="0.6.0" />
     <PackageVersion Include="iTextSharp" Version="5.5.13.3" />
     <PackageVersion Include="Jint" Version="3.0.0-beta-2048" />
     <PackageVersion Include="JsonSchema.Net" Version="4.0.2" />

diff --git a/src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/MetadataItem.cs b/src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/MetadataItem.cs
@@ -16,10 +16,6 @@ internal class MetadataItem : ICloneable
     [JsonIgnore]
     public bool IsInvalid { get; set; }
 
-    [YamlIgnore]
-    [JsonIgnore]
-    public string RawComment { get; set; }
-
     [JsonProperty(Constants.PropertyName.IsEii)]
     [YamlMember(Alias = Constants.PropertyName.IsEii)]
     public bool IsExplicitInterfaceImplementation { get; set; }
@@ -137,10 +133,6 @@ internal class MetadataItem : ICloneable
     [JsonProperty("references")]
     public Dictionary<string, ReferenceItem> References { get; set; }
 
-    [YamlIgnore]
-    [JsonIgnore]
-    public string InheritDoc { get; set; }
-
     [YamlIgnore]
     [JsonIgnore]
     public XmlComment CommentModel { get; set; }
@@ -154,27 +146,4 @@ public object Clone()
     {
         return MemberwiseClone();
     }
-
-    public void CopyInheritedData(MetadataItem src)
-    {
-        if (src == null)
-            throw new ArgumentNullException(nameof(src));
-
-        if (Summary == null)
-            Summary = src.Summary;
-        if (Remarks == null)
-            Remarks = src.Remarks;
-
-        if (Exceptions == null && src.Exceptions != null)
-            Exceptions = src.Exceptions.Select(e => e.Clone()).ToList();
-        if (SeeAlsos == null && src.SeeAlsos != null)
-            SeeAlsos = src.SeeAlsos.Select(s => s.Clone()).ToList();
-        if (Examples == null && src.Examples != null)
-            Examples = new List<string>(src.Examples);
-
-        if (CommentModel != null && src.CommentModel != null)
-            CommentModel.CopyInheritedData(src.CommentModel);
-        if (Syntax != null && src.Syntax != null)
-            Syntax.CopyInheritedData(src.Syntax);
-    }
 }
diff --git a/src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/SyntaxDetail.cs b/src/Microsoft.DocAsCode.Dotnet/ExtractMetadata/SyntaxDetail.cs
@@ -25,30 +25,4 @@ internal class SyntaxDetail
     [YamlMember(Alias = "return")]
     [JsonProperty("return")]
     public ApiParameter Return { get; set; }
-
-    internal void CopyInheritedData(SyntaxDetail src)
-    {
-        if (src == null)
-            throw new ArgumentNullException(nameof(src));
-
-        CopyInheritedParameterList(Parameters, src.Parameters);
-        CopyInheritedParameterList(TypeParameters, src.TypeParameters);
-        if (Return != null && src.Return != null)
-            Return.CopyInheritedData(src.Return);
-    }
-
-    static void CopyInheritedParameterList(List<ApiParameter> dest, List<ApiParameter> src)
-    {
-        if (dest == null || src == null || dest.Count != src.Count)
-            return;
-        for (int ndx = 0; ndx < dest.Count; ndx++)
-        {
-            var myParam = dest[ndx];
-            var srcParam = src[ndx];
-            if (myParam.Name == srcParam.Name && myParam.Type == srcParam.Type)
-            {
-                myParam.CopyInheritedData(srcParam);
-            }
-        }
-    }
 }
diff --git a/src/Microsoft.DocAsCode.Dotnet/ManagedReference/ApiParameter.cs b/src/Microsoft.DocAsCode.Dotnet/ManagedReference/ApiParameter.cs
@@ -31,13 +31,4 @@ public class ApiParameter
     [JsonProperty("attributes")]
     [MergeOption(MergeOption.Ignore)]
     public List<AttributeInfo> Attributes { get; set; }
-
-    internal void CopyInheritedData(ApiParameter src)
-    {
-        if (src == null)
-            throw new ArgumentNullException(nameof(src));
-
-        if (Description == null)
-            Description = src.Description;
-    }
 }
diff --git a/src/Microsoft.DocAsCode.Dotnet/Microsoft.DocAsCode.Dotnet.csproj b/src/Microsoft.DocAsCode.Dotnet/Microsoft.DocAsCode.Dotnet.csproj
@@ -20,6 +20,7 @@
 
   <ItemGroup>
     <PackageReference Include="ICSharpCode.Decompiler" />
+    <PackageReference Include="IgnoresAccessChecksToGenerator" PrivateAssets="All" />
     <PackageReference Include="System.Configuration.ConfigurationManager" />
     <PackageReference Include="Microsoft.Build" ExcludeAssets="runtime" />
     <PackageReference Include="Microsoft.Build.Locator" />
@@ -32,4 +33,9 @@
     <PackageReference Include="Microsoft.CodeAnalysis.Workspaces.Common" />
     <PackageReference Include="Microsoft.CodeAnalysis.Workspaces.MSBuild" />
   </ItemGroup>
+
+  <ItemGroup>
+    <InternalsAssemblyName Include="Microsoft.CodeAnalysis.Workspaces" />
+  </ItemGroup>
+
 </Project>
diff --git a/src/Microsoft.DocAsCode.Dotnet/Resolvers/CopyInheritedDocumentation.cs b/src/Microsoft.DocAsCode.Dotnet/Resolvers/CopyInheritedDocumentation.cs
diff --git a/src/Microsoft.DocAsCode.Dotnet/Resolvers/YamlMetadataResolver.cs b/src/Microsoft.DocAsCode.Dotnet/Resolvers/YamlMetadataResolver.cs
@@ -12,7 +12,6 @@ internal static class YamlMetadataResolver
     {
         new LayoutCheckAndCleanup(),
         new SetParent(),
-        new CopyInherited(),
         new ResolveReference(),
         new NormalizeSyntax(),
         new BuildMembers(),

diff --git a/src/Microsoft.DocAsCode.Dotnet/Visitors/SymbolVisitorAdapter.cs b/src/Microsoft.DocAsCode.Dotnet/Visitors/SymbolVisitorAdapter.cs
@@ -6,6 +6,7 @@
 using System.Text.RegularExpressions;
 
 using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.Shared.Extensions;
 using Microsoft.DocAsCode.DataContracts.ManagedReference;
 using Microsoft.DocAsCode.Exceptions;
 
@@ -37,11 +38,11 @@ public override MetadataItem DefaultVisit(ISymbol symbol)
         {
             return null;
         }
+
         var item = new MetadataItem
         {
             Name = VisitorHelper.GetId(symbol),
             CommentId = VisitorHelper.GetCommentId(symbol),
-            RawComment = symbol.GetDocumentationCommentXml(expandIncludes: true),
         };
 
         item.DisplayNames = new SortedList<SyntaxLanguage, string>();
@@ -50,13 +51,23 @@ public override MetadataItem DefaultVisit(ISymbol symbol)
         item.Source = VisitorHelper.GetSourceDetail(symbol, _compilation);
         var assemblyName = symbol.ContainingAssembly?.Name;
         item.AssemblyNameList = string.IsNullOrEmpty(assemblyName) ? null : new List<string> { assemblyName };
-        if (!(symbol is INamespaceSymbol))
+        if (symbol is not INamespaceSymbol)
         {
             var namespaceName = VisitorHelper.GetId(symbol.ContainingNamespace);
             item.NamespaceName = string.IsNullOrEmpty(namespaceName) ? null : namespaceName;
         }
 
-        VisitorHelper.FeedComments(item, GetXmlCommentParserContext(item));
+        var comment = symbol.GetDocumentationComment(_compilation, expandIncludes: true, expandInheritdoc: true);
+        if (XmlComment.Parse(comment.FullXmlFragment, GetXmlCommentParserContext(item)) is { } commentModel)
+        {
+            item.Summary = commentModel.Summary;
+            item.Remarks = commentModel.Remarks;
+            item.Exceptions = commentModel.Exceptions;
+            item.SeeAlsos = commentModel.SeeAlsos;
+            item.Examples = commentModel.Examples;
+            item.CommentModel = commentModel;
+        }
+
         if (item.Exceptions != null)
         {
             foreach (var exceptions in item.Exceptions)
@@ -82,7 +93,6 @@ public override MetadataItem VisitAssembly(IAssemblySymbol symbol)
         var item = new MetadataItem
         {
             Name = VisitorHelper.GetId(symbol),
-            RawComment = symbol.GetDocumentationCommentXml(expandIncludes: true),
         };
 
         item.DisplayNames = new SortedList<SyntaxLanguage, string>

diff --git a/src/Microsoft.DocAsCode.Dotnet/Visitors/VisitorHelper.cs b/src/Microsoft.DocAsCode.Dotnet/Visitors/VisitorHelper.cs
@@ -19,22 +19,6 @@ internal static class VisitorHelper
     public static string GlobalNamespaceId { get; set; }
     private static readonly Regex GenericMethodPostFix = new(@"``\d+$", RegexOptions.Compiled);
 
-    public static void FeedComments(MetadataItem item, XmlCommentParserContext context)
-    {
-        if (!string.IsNullOrEmpty(item.RawComment))
-        {
-            var commentModel = XmlComment.Parse(item.RawComment, context);
-            if (commentModel == null) return;
-            item.Summary = commentModel.Summary;
-            item.Remarks = commentModel.Remarks;
-            item.Exceptions = commentModel.Exceptions;
-            item.SeeAlsos = commentModel.SeeAlsos;
-            item.Examples = commentModel.Examples;
-            item.InheritDoc = commentModel.InheritDoc;
-            item.CommentModel = commentModel;
-        }
-    }
-
     public static string GetId(ISymbol symbol)
     {
         if (symbol == null)