feat: UseClrTypeNames: new option to indicate that the output must us…

…e the CLR type names instead of the language specific aliases (#10072) * UseClrTypeNames: new option to indicate that the output must use the CLR type names instead of the language specific aliases. * Updated the schema with the new parameter. * Updated the documentation with the new parameter.
dotnet · Jul 9, 2024 · 1bb332a · 1bb332a
1 parent d3c3327
commit 1bb332a
Show file tree

Hide file tree

Showing 7 changed files with 50 additions and 9 deletions.
diff --git a/docs/reference/docfx-cli-reference/docfx-metadata.md b/docs/reference/docfx-cli-reference/docfx-metadata.md
@@ -95,11 +95,19 @@ Run `docfx metadata --help` or `docfx -h` to get a list of all available options
   - `SeparatePages`
     - Place members in separate pages.
 
+- **--useClrTypeNames**
+
+  Indicates whether the CLR type names or the language aliases must be used.
+
+    - not specified or `false`
+        - The language aliases are used: `int`.
+    - `true`
+        - The CLR type names are used: `Int32`.
+
 ## Examples
 
 - Generate YAML files with default config.
 
 ```pwsh
 docfx metadata
 ```
-
diff --git a/schemas/docfx.schema.json b/schemas/docfx.schema.json
@@ -692,6 +692,11 @@
             "type": "boolean",
             "default": false,
             "description": "When enabled, continues documentation generation in case of compilation errors."
+          },
+          "useClrTypeNames": {
+            "type": "boolean",
+            "default": false,
+            "description": "When enabled, use CLR type names instead of language aliases."
           }
         }
       }

diff --git 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
@@ -42,4 +42,7 @@ internal class ExtractMetadataConfig
     public Dictionary<string, string> 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
@@ -258,6 +258,13 @@ internal class MetadataJsonItemConfig
     [JsonProperty("allowCompilationErrors")]
     [JsonPropertyName("allowCompilationErrors")]
     public bool AllowCompilationErrors { get; set; }
+
+    /// <summary>
+    ///   When enabled, the types uses the CLR type names instead of the C# aliases.
+    /// </summary>
+    [JsonProperty("useClrTypeNames")]
+    [JsonPropertyName("useClrTypeNames")]
+    public bool UseClrTypeNames { get; init; }
 }
 
 /// <summary>

diff --git a/src/Docfx.Dotnet/SymbolFormatter.Syntax.cs b/src/Docfx.Dotnet/SymbolFormatter.Syntax.cs
@@ -38,17 +38,24 @@ 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,
             extensionMethodStyle: SymbolDisplayExtensionMethodStyle.StaticMethod,
             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
@@ -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