feat: option to sort enum member in declaring order (dotnet#9093)

docs/reference/docfx-json-reference.md

@@ -339,16 +339,29 @@ Do not run `dotnet restore` before building the projects.
 
 ### `namespaceLayout`
 
-Defines how namespaces in TOC are organized. When set to *flattened*, renders namespaces as a single flat list. When set to *nested*, renders namespaces in a nested tree form. The default is *flattened*.
+Defines how namespaces in TOC are organized:
+
+- `flattened` (default): Renders namespaces as a single flat list.
+- `nested`: Renders namespaces in a nested tree form.
 
 ### `memberLayout`
 
-Defines how member pages are organized. When set to *samePage*, places members in the same page as their containing type. When set to *separatePages*, places members in separate pages. The default is *samePage*.
+Defines how member pages are organized:
+
+- `samePage` (default): Places members in the same page as their containing type.
+- `separatePages`: Places members in separate pages.
 
 ### `allowCompilationErrors`
 
 When enabled, continues documentation generation in case of compilation errors.
 
+### `EnumSortOrder`
+
+Defines how enum members are sorted:
+
+- `alphabetic` (default): Sort enum members in alphabetic order.
+- `declaringOrder`: Sort enum members in the order as they are declared in the source code.
+
 ## `pdf`
 
 Configuration options that are applied for `docfx pdf` command:

samples/seed/docfx.json

@@ -17,6 +17,7 @@
         }
       ],
       "namespaceLayout": "nested",
+      "enumSortOrder": "declaringOrder",
       "dest": "obj/api"
     }
   ],

src/Docfx.Dotnet/DotnetApiCatalog.cs

@@ -125,6 +125,7 @@ private static ExtractMetadataConfig ConvertConfig(MetadataJsonItemConfig config
             NoRestore = configModel?.NoRestore ?? false,
             NamespaceLayout = configModel?.NamespaceLayout ?? default,
             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(),

src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataConfig.cs

@@ -29,6 +29,8 @@ internal class ExtractMetadataConfig
 
     public MemberLayout MemberLayout { get; init; }
 
+    public EnumSortOrder EnumSortOrder { get; init; }
+
     public Dictionary<string, string> MSBuildProperties { get; init; }
 
     public bool AllowCompilationErrors { get; init; }

src/Docfx.Dotnet/ExtractMetadata/ExtractMetadataWorker.cs

@@ -232,7 +232,7 @@ private void ResolveAndExportYamlMetadata(
             var fileName = memberModel.Name.Replace('`', '-');
             var outputFileName = GetUniqueFileNameWithSuffix(fileName + Constants.YamlExtension, outputFileNames);
             string itemFilePath = Path.Combine(_config.OutputFolder, outputFileName);
-            var memberViewModel = memberModel.ToPageViewModel();
+            var memberViewModel = memberModel.ToPageViewModel(_config);
             memberViewModel.ShouldSkipMarkup = _config.ShouldSkipMarkup;
             memberViewModel.MemberLayout = _config.MemberLayout;
             YamlUtility.Serialize(itemFilePath, memberViewModel, YamlMime.ManagedReference);

src/Docfx.Dotnet/MetadataJsonConfig.cs

@@ -31,6 +31,22 @@ internal enum NamespaceLayout
     Nested,
 }
 
+/// <summary>
+/// Specifies the sort order for enums.
+/// </summary>
+internal enum EnumSortOrder
+{
+    /// <summary>
+    /// Sorts enums in alphabetic order.
+    /// </summary>
+    Alphabetic,
+
+    /// <summary>
+    /// Sorts enums in the order they are declared.
+    /// </summary>
+    DeclaringOrder
+}
+
 /// <summary>
 /// MetadataJsonItemConfig.
 /// </summary>
@@ -67,7 +83,6 @@ internal class MetadataJsonItemConfig
     [JsonProperty("filter")]
     public string FilterConfigFile { get; set; }
 
-
     /// <summary>
     /// Include private or internal APIs.
     /// The default is false.
@@ -114,23 +129,28 @@ internal class MetadataJsonItemConfig
     public bool NoRestore { get; set; }
 
     /// <summary>
-    /// Defines how namespaces in TOC are organized.
-    /// When set to flattened, renders namespaces as a single flat list.
-    /// When set to nested, renders namespaces in a nested tree form.
-    /// The default is flattened.
+    /// Defines how namespaces in TOC are organized:
+    /// - `flattened` (default): Renders namespaces as a single flat list.
+    /// - `nested`: Renders namespaces in a nested tree form.
     /// </summary>
     [JsonProperty("namespaceLayout")]
     public NamespaceLayout NamespaceLayout { get; set; }
 
     /// <summary>
-    /// Defines how member pages are organized.
-    /// When set to samePage, places members in the same page as their containing type.
-    /// When set to separatePages, places members in separate pages.
-    /// The default is samePage.
+    /// Defines how member pages are organized:
+    /// - `samePage` (default): Places members in the same page as their containing type.
+    /// - `separatePages`: Places members in separate pages.
     /// </summary>
     [JsonProperty("memberLayout")]
     public MemberLayout MemberLayout { get; set; }
 
+    /// <summary>
+    /// Defines how member pages are organized:
+    /// - `samePage` (default): Places members in the same page as their containing type.
+    /// - `separatePages`: Places members in separate pages.
+    /// </summary>
+    public EnumSortOrder EnumSortOrder { get; init; }
+
     /// <summary>
     /// When enabled, continues documentation generation in case of compilation errors.
     /// </summary>

src/Docfx.Dotnet/YamlViewModelExtensions.cs

@@ -150,17 +150,17 @@ public static TocItemViewModel ToTocItemViewModel(this MetadataItem item, string
         return result;
     }
 
-    public static PageViewModel ToPageViewModel(this MetadataItem model)
+    public static PageViewModel ToPageViewModel(this MetadataItem model, ExtractMetadataConfig config)
     {
         if (model == null)
         {
             return null;
         }
         var result = new PageViewModel();
-        result.Items.Add(model.ToItemViewModel());
+        result.Items.Add(model.ToItemViewModel(config));
         if (model.Type.AllowMultipleItems())
         {
-            AddChildren(model, result);
+            AddChildren(model, result, config);
         }
         foreach (var item in model.References)
         {
@@ -229,21 +229,25 @@ private static ReferenceViewModel ToReferenceViewModel(KeyValuePair<string, Refe
         return result;
     }
 
-    public static ItemViewModel ToItemViewModel(this MetadataItem model)
+    public static ItemViewModel ToItemViewModel(this MetadataItem model, ExtractMetadataConfig config)
     {
         if (model == null)
         {
             return null;
         }
 
+        var children = model.Type is MemberType.Enum && config.EnumSortOrder is EnumSortOrder.DeclaringOrder
+            ? model.Items?.Select(x => x.Name).ToList()
+            : model.Items?.Select(x => x.Name).OrderBy(s => s, StringComparer.Ordinal).ToList();
+
         var result = new ItemViewModel
         {
             Uid = model.Name,
             CommentId = model.CommentId,
             IsExplicitInterfaceImplementation = model.IsExplicitInterfaceImplementation,
             IsExtensionMethod = model.IsExtensionMethod,
             Parent = model.Parent?.Name,
-            Children = model.Items?.Select(x => x.Name).OrderBy(s => s, StringComparer.Ordinal).ToList(),
+            Children = children,
             Type = model.Type,
             Source = model.Source,
             Documentation = model.Documentation,
@@ -372,14 +376,14 @@ public static TValue GetLanguageProperty<TValue>(this SortedList<SyntaxLanguage,
         return defaultValue;
     }
 
-    private static void AddChildren(MetadataItem model, PageViewModel result)
+    private static void AddChildren(MetadataItem model, PageViewModel result, ExtractMetadataConfig config)
     {
         if (model.Items != null && model.Items.Count > 0)
         {
             foreach (var item in model.Items)
             {
-                result.Items.Add(item.ToItemViewModel());
-                AddChildren(item, result);
+                result.Items.Add(item.ToItemViewModel(config));
+                AddChildren(item, result, config);
             }
         }
     }