feat: organize stub package contents

third_party/docfx-doclet-143274/src/main/java/com/microsoft/build/ClassBuilder.java

@@ -24,6 +24,7 @@
 import com.microsoft.model.ApiVersionPackageToc;
 import com.microsoft.model.MetadataFile;
 import com.microsoft.model.MetadataFileItem;
+import com.microsoft.model.StubPackageToc;
 import com.microsoft.model.TocItem;
 import com.microsoft.model.TocTypeMap;
 import com.microsoft.util.ElementUtil;
@@ -69,6 +70,11 @@ List<TocItem> buildFilesForPackage(PackageElement pkg, List<MetadataFile> classM
       buildFilesForApiVersionPackage(pkg, apiVersionPackageToc, classMetadataFiles);
       return apiVersionPackageToc.toList();
 
+    } else if (packageLookup.isApiVersionStubPackage(pkg)) {
+      StubPackageToc stubPackageToc = new StubPackageToc();
+      buildFilesForStubPackage(pkg, stubPackageToc, classMetadataFiles);
+      return stubPackageToc.toList();
+
     } else {
       // Standard package organization is a flat list organized by Java type
       TocTypeMap typeMap = new TocTypeMap();
@@ -118,6 +124,29 @@ private void buildFilesForApiVersionPackage(
     }
   }
 
+  private void buildFilesForStubPackage(
+      Element element, StubPackageToc packageToc, List<MetadataFile> classMetadataFiles) {
+    for (TypeElement classElement : elementUtil.extractSortedElements(element)) {
+      String uid = classLookup.extractUid(classElement);
+      String name = classLookup.extractTocName(classElement);
+      String status = classLookup.extractStatus(classElement);
+      TocItem tocItem = new TocItem(uid, name, status);
+
+      if (name.endsWith("Stub")) {
+        packageToc.addStub(tocItem);
+      } else if (name.contains("Settings")) {
+        packageToc.addSettings(tocItem);
+      } else if (name.endsWith("CallableFactory")) {
+        packageToc.addCallableFactory(tocItem);
+      } else {
+        packageToc.addUncategorized(tocItem);
+      }
+
+      classMetadataFiles.add(buildClassYmlFile(classElement));
+      buildFilesForStubPackage(classElement, packageToc, classMetadataFiles);
+    }
+  }
+
   boolean containsAtLeastOneClient(PackageElement pkg) {
     return elementUtil.extractSortedElements(pkg).stream().anyMatch(this::isClient);
   }

third_party/docfx-doclet-143274/src/main/java/com/microsoft/model/StubPackageToc.java

@@ -0,0 +1,59 @@
+package com.microsoft.model;
+
+import java.util.ArrayList;
+import java.util.Comparator;
+import java.util.LinkedHashMap;
+import java.util.List;
+
+public class StubPackageToc {
+  static final String STUBS = "Stubs";
+  static final String SETTINGS = "Settings";
+  static final String CALLABLE_FACTORIES = "Callable factories";
+  static final String UNCATEGORIZED = "Other";
+
+  private final LinkedHashMap<String, List<TocItem>> visibleCategories = new LinkedHashMap<>();
+
+  public StubPackageToc() {
+    // Order here determines final organization order.
+    visibleCategories.put(STUBS, new ArrayList<>());
+    visibleCategories.put(SETTINGS, new ArrayList<>());
+    visibleCategories.put(CALLABLE_FACTORIES, new ArrayList<>());
+  }
+
+  public void addStub(TocItem tocItem) {
+    visibleCategories.get(STUBS).add(tocItem);
+  }
+
+  public void addSettings(TocItem tocItem) {
+    visibleCategories.get(SETTINGS).add(tocItem);
+  }
+
+  public void addCallableFactory(TocItem tocItem) {
+    visibleCategories.get(CALLABLE_FACTORIES).add(tocItem);
+  }
+
+  public void addUncategorized(TocItem tocItem) {
+    visibleCategories.get(UNCATEGORIZED).add(tocItem);
+  }
+
+  /** Build a list of TocItems for inclusion in the library's table of contents */
+  public List<TocItem> toList() {
+    List<TocItem> toc = new ArrayList<>();
+
+    visibleCategories.forEach(
+        (name, category) -> {
+          if (!category.isEmpty()) {
+            toc.add(createCategory(name, category));
+          }
+        });
+
+    return toc;
+  }
+
+  private TocItem createCategory(String name, List<TocItem> items) {
+    TocItem category = new TocItem(name, name, null);
+    items.sort(Comparator.comparing(TocItem::getName));
+    category.getItems().addAll(items);
+    return category;
+  }
+}