From a528507da25c5a916add7e42bc8fafcbe3aa745e Mon Sep 17 00:00:00 2001 From: Patrick8639 Date: Mon, 8 Jul 2024 11:10:06 +0200 Subject: [PATCH 1/2] UseClrTypeNames: new option to indicate that the output must use the CLR type names instead of the language specific aliases. --- src/Docfx.Dotnet/DotnetApiCatalog.cs | 2 ++ .../ManagedReference/ExtractMetadataConfig.cs | 3 +++ src/Docfx.Dotnet/MetadataJsonConfig.cs | 7 +++++++ src/Docfx.Dotnet/SymbolFormatter.Syntax.cs | 15 +++++++++++---- src/Docfx.Dotnet/SymbolFormatter.cs | 17 +++++++++++++---- 5 files changed, 36 insertions(+), 8 deletions(-) diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.cs b/src/Docfx.Dotnet/DotnetApiCatalog.cs index 0c9c5da1f06..fead74514a1 100644 --- a/src/Docfx.Dotnet/DotnetApiCatalog.cs +++ b/src/Docfx.Dotnet/DotnetApiCatalog.cs @@ -148,6 +148,8 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config var expandedFiles = GlobUtility.ExpandFileMapping(EnvironmentContext.BaseDirectory, projects); var expandedReferences = GlobUtility.ExpandFileMapping(EnvironmentContext.BaseDirectory, references); + ExtractMetadataConfig.UseClrTypeNames = configModel?.UseClrTypeNames ?? false; + return new ExtractMetadataConfig { ShouldSkipMarkup = configModel?.ShouldSkipMarkup ?? false, diff --git a/src/Docfx.Dotnet/ManagedReference/ExtractMetadataConfig.cs b/src/Docfx.Dotnet/ManagedReference/ExtractMetadataConfig.cs index cf8b4674713..0cf7164962e 100644 --- a/src/Docfx.Dotnet/ManagedReference/ExtractMetadataConfig.cs +++ b/src/Docfx.Dotnet/ManagedReference/ExtractMetadataConfig.cs @@ -42,4 +42,7 @@ internal class ExtractMetadataConfig public Dictionary MSBuildProperties { get; init; } public bool AllowCompilationErrors { get; init; } + + public static bool UseClrTypeNames { get; set; } + } diff --git a/src/Docfx.Dotnet/MetadataJsonConfig.cs b/src/Docfx.Dotnet/MetadataJsonConfig.cs index 148a3b92f42..1bf92029531 100644 --- a/src/Docfx.Dotnet/MetadataJsonConfig.cs +++ b/src/Docfx.Dotnet/MetadataJsonConfig.cs @@ -258,6 +258,13 @@ internal class MetadataJsonItemConfig [JsonProperty("allowCompilationErrors")] [JsonPropertyName("allowCompilationErrors")] public bool AllowCompilationErrors { get; set; } + + /// + /// When enabled, the types uses the CLR type names instead of the C# aliases. + /// + [JsonProperty("useClrTypeNames")] + [JsonPropertyName("useClrTypeNames")] + public bool UseClrTypeNames { get; init; } } /// diff --git a/src/Docfx.Dotnet/SymbolFormatter.Syntax.cs b/src/Docfx.Dotnet/SymbolFormatter.Syntax.cs index d4072fd286f..0a5dac67529 100644 --- a/src/Docfx.Dotnet/SymbolFormatter.Syntax.cs +++ b/src/Docfx.Dotnet/SymbolFormatter.Syntax.cs @@ -38,8 +38,10 @@ class SyntaxFormatter SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier | SymbolDisplayMiscellaneousOptions.EscapeKeywordIdentifiers | SymbolDisplayMiscellaneousOptions.AllowDefaultLiteral | - SymbolDisplayMiscellaneousOptions.UseSpecialTypes | - SymbolDisplayMiscellaneousOptions.RemoveAttributeSuffix, + SymbolDisplayMiscellaneousOptions.RemoveAttributeSuffix | + (ExtractMetadataConfig.UseClrTypeNames + ? SymbolDisplayMiscellaneousOptions.None + : SymbolDisplayMiscellaneousOptions.UseSpecialTypes), localOptions: SymbolDisplayLocalOptions.IncludeType, propertyStyle: SymbolDisplayPropertyStyle.ShowReadWriteDescriptor, delegateStyle: SymbolDisplayDelegateStyle.NameAndSignature, @@ -47,8 +49,13 @@ class SyntaxFormatter typeQualificationStyle: SymbolDisplayTypeQualificationStyle.NameAndContainingTypes); private static readonly SymbolDisplayFormat s_syntaxTypeNameFormat = new( - genericsOptions: SymbolDisplayGenericsOptions.IncludeTypeParameters, - miscellaneousOptions: SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier | SymbolDisplayMiscellaneousOptions.UseSpecialTypes, + genericsOptions: + SymbolDisplayGenericsOptions.IncludeTypeParameters, + miscellaneousOptions: + SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier | + (ExtractMetadataConfig.UseClrTypeNames + ? SymbolDisplayMiscellaneousOptions.None + : SymbolDisplayMiscellaneousOptions.UseSpecialTypes), typeQualificationStyle: SymbolDisplayTypeQualificationStyle.NameAndContainingTypes); private static readonly SymbolDisplayFormat s_syntaxEnumConstantFormat = s_syntaxFormat diff --git a/src/Docfx.Dotnet/SymbolFormatter.cs b/src/Docfx.Dotnet/SymbolFormatter.cs index bc305e4c5d8..d6fc9c4eac4 100644 --- a/src/Docfx.Dotnet/SymbolFormatter.cs +++ b/src/Docfx.Dotnet/SymbolFormatter.cs @@ -9,10 +9,19 @@ namespace Docfx.Dotnet; internal static partial class SymbolFormatter { private static readonly SymbolDisplayFormat s_nameFormat = new( - memberOptions: SymbolDisplayMemberOptions.IncludeParameters | SymbolDisplayMemberOptions.IncludeExplicitInterface, - genericsOptions: SymbolDisplayGenericsOptions.IncludeTypeParameters, - parameterOptions: SymbolDisplayParameterOptions.IncludeType, - miscellaneousOptions: SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier | SymbolDisplayMiscellaneousOptions.AllowDefaultLiteral | SymbolDisplayMiscellaneousOptions.UseSpecialTypes, + memberOptions: + SymbolDisplayMemberOptions.IncludeParameters | + SymbolDisplayMemberOptions.IncludeExplicitInterface, + genericsOptions: + SymbolDisplayGenericsOptions.IncludeTypeParameters, + parameterOptions: + SymbolDisplayParameterOptions.IncludeType, + miscellaneousOptions: + SymbolDisplayMiscellaneousOptions.IncludeNullableReferenceTypeModifier | + SymbolDisplayMiscellaneousOptions.AllowDefaultLiteral | + (ExtractMetadataConfig.UseClrTypeNames + ? SymbolDisplayMiscellaneousOptions.None + : SymbolDisplayMiscellaneousOptions.UseSpecialTypes), extensionMethodStyle: SymbolDisplayExtensionMethodStyle.StaticMethod); private static readonly SymbolDisplayFormat s_nameWithTypeFormat = s_nameFormat From 0164a3033707747c73c9c5bf2e0a327d8dcd66fd Mon Sep 17 00:00:00 2001 From: Patrick8639 Date: Mon, 8 Jul 2024 11:18:37 +0200 Subject: [PATCH 2/2] Source code improvements --- src/Docfx.Build/CompilePhaseHandler.cs | 4 ++-- src/Docfx.Build/DocumentBuilder.cs | 4 ++-- src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs | 7 +++++-- src/Docfx.Dotnet/DotnetApiCatalog.ManagedReference.cs | 3 +++ src/Docfx.Dotnet/DotnetApiCatalog.cs | 4 ++-- 5 files changed, 14 insertions(+), 8 deletions(-) diff --git a/src/Docfx.Build/CompilePhaseHandler.cs b/src/Docfx.Build/CompilePhaseHandler.cs index 1dc41221526..e6ad1537014 100644 --- a/src/Docfx.Build/CompilePhaseHandler.cs +++ b/src/Docfx.Build/CompilePhaseHandler.cs @@ -26,7 +26,7 @@ public void Handle(List hostServices, int maxParallelism) Prepare(hostServices, maxParallelism); hostServices.RunAll(hostService => { - var steps = string.Join("=>", hostService.Processor.BuildSteps.OrderBy(step => step.BuildOrder).Select(s => s.Name)); + var steps = string.Join("=>", hostService.Processor.BuildSteps.OrderBy(static step => step.BuildOrder).Select(static s => s.Name)); Logger.LogInfo($"Building {hostService.Models.Count} file(s) in {hostService.Processor.Name}({steps})..."); Logger.LogVerbose($"Processor {hostService.Processor.Name}: Prebuilding..."); Prebuild(hostService); @@ -144,7 +144,7 @@ private static void RunBuildSteps(IEnumerable buildSteps, Ac { if (buildSteps != null) { - foreach (var buildStep in buildSteps.OrderBy(step => step.BuildOrder)) + foreach (var buildStep in buildSteps.OrderBy(static step => step.BuildOrder)) { action(buildStep); } diff --git a/src/Docfx.Build/DocumentBuilder.cs b/src/Docfx.Build/DocumentBuilder.cs index 85af3e459e1..94453ede768 100644 --- a/src/Docfx.Build/DocumentBuilder.cs +++ b/src/Docfx.Build/DocumentBuilder.cs @@ -92,11 +92,11 @@ public void Build(IList parameters, string outputDirect if (parameter.Files.Count == 0) { - manifests.Add(new Manifest() { SourceBasePath = StringExtension.ToNormalizedPath(EnvironmentContext.BaseDirectory) }); + manifests.Add(new Manifest { SourceBasePath = StringExtension.ToNormalizedPath(EnvironmentContext.BaseDirectory) }); } else { - if (!parameter.Files.EnumerateFiles().Any(s => s.Type == DocumentType.Article)) + if (!parameter.Files.EnumerateFiles().Any(static s => s.Type == DocumentType.Article)) { if (!string.IsNullOrEmpty(parameter.GroupInfo?.Name)) { diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs b/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs index 8dd02350c9a..7842c8b625f 100644 --- a/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs +++ b/src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs @@ -602,18 +602,21 @@ void EnumFields(INamedTypeSymbol type) return; if (config.EnumSortOrder is EnumSortOrder.Alphabetic) - items = items.OrderBy(m => m.Name).ToList(); + items = items.OrderBy(static m => m.Name).ToList(); body.Add((Heading)new H2 { h2 = "Fields" }); body.Add(new Parameters { parameters = items.Select(ToParameter).ToArray() }); + return; + Parameter ToParameter(IFieldSymbol item) { var docs = Comment(item, compilation) is { } comment ? string.Join("\n\n", comment.Summary, comment.Remarks) : null; return new() { - name = item.Name, @default = $"{item.ConstantValue}", + name = item.Name, + @default = $"{item.ConstantValue}", deprecated = Deprecated(item), preview = Preview(item), description = docs, diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.ManagedReference.cs b/src/Docfx.Dotnet/DotnetApiCatalog.ManagedReference.cs index e619ded5880..3a8e0fd6b2f 100644 --- a/src/Docfx.Dotnet/DotnetApiCatalog.ManagedReference.cs +++ b/src/Docfx.Dotnet/DotnetApiCatalog.ManagedReference.cs @@ -44,6 +44,9 @@ private static void CreateManagedReference(List<(IAssemblySymbol symbol, Compila ResolveAndExportYamlMetadata(allMembers, allReferences); + return; + + void ResolveAndExportYamlMetadata( Dictionary allMembers, Dictionary allReferences) { diff --git a/src/Docfx.Dotnet/DotnetApiCatalog.cs b/src/Docfx.Dotnet/DotnetApiCatalog.cs index fead74514a1..3e18375fc28 100644 --- a/src/Docfx.Dotnet/DotnetApiCatalog.cs +++ b/src/Docfx.Dotnet/DotnetApiCatalog.cs @@ -169,8 +169,8 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config MemberLayout = configModel?.MemberLayout ?? default, EnumSortOrder = configModel?.EnumSortOrder ?? default, AllowCompilationErrors = configModel?.AllowCompilationErrors ?? false, - Files = expandedFiles.Items.SelectMany(s => s.Files).ToList(), - References = expandedReferences?.Items.SelectMany(s => s.Files).ToList(), + Files = expandedFiles.Items.SelectMany(static s => s.Files).ToList(), + References = expandedReferences?.Items.SelectMany(static s => s.Files).ToList() }; } }