feat: order toc by type

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

@@ -13,10 +13,7 @@
 import org.apache.commons.lang3.RegExUtils;
 import org.apache.commons.lang3.StringUtils;
 
-import javax.lang.model.element.Element;
-import javax.lang.model.element.ExecutableElement;
-import javax.lang.model.element.PackageElement;
-import javax.lang.model.element.TypeElement;
+import javax.lang.model.element.*;
 import javax.lang.model.util.ElementFilter;
 import java.util.*;
 import java.util.function.Function;
@@ -72,7 +69,11 @@ public boolean build() {
             TocItem packageTocItem = new TocItem(uid, uid, status);
             packageMetadataFiles.add(buildPackageMetadataFile(packageElement));
             packageTocItem.getItems().add(new TocItem(uid, "Package summary"));
-            buildFilesForInnerClasses(packageElement, packageTocItem.getItems(), classMetadataFiles);
+
+            TocTypeMap typeMap = new TocTypeMap();
+            buildFilesForInnerClasses(packageElement,typeMap, classMetadataFiles);
+            packageTocItem.getItems().addAll(joinTocTypeItems(typeMap));
+
             tocFile.addTocItem(packageTocItem);
         }
 
@@ -98,16 +99,33 @@ public boolean build() {
         return true;
     }
 
-    void buildFilesForInnerClasses(Element element, List<TocItem> listToAddItems, List<MetadataFile> container) {
+    List<TocItem> joinTocTypeItems(TocTypeMap tocTypeMap){
+        return tocTypeMap.getTitleList().stream()
+                .filter(kindTitle -> tocTypeMap.get(kindTitle.getElementKind()).size() > 0)
+                .flatMap(kindTitle -> {
+                    tocTypeMap.get(kindTitle.getElementKind()).add(0, new TocItem(kindTitle.getTitle()));
+                    return tocTypeMap.get(kindTitle.getElementKind()).stream();
+                }).collect(Collectors.toList());
+    }
+
+    void buildFilesForInnerClasses(Element element, TocTypeMap tocTypeMap, List<MetadataFile> container) {
         for (TypeElement classElement : elementUtil.extractSortedElements(element)) {
             String uid = classLookup.extractUid(classElement);
             String name = classLookup.extractTocName(classElement);
             String status = classLookup.extractStatus(classElement);
 
-            listToAddItems.add(new TocItem(uid, name, status));
+            if (tocTypeMap.get(classElement.getKind().name()) != null) {
+                if (classElement.getKind().name().equals(ElementKind.CLASS.name()) && name.contains("Exception")) {
+                    tocTypeMap.get("EXCEPTION").add(new TocItem(uid, name, status));
+                } else {
+                    tocTypeMap.get(classElement.getKind().name()).add(new TocItem(uid, name, status));
+                }
+            } else {
+                tocTypeMap.get(ElementKind.CLASS.name()).add(new TocItem(uid, name, status));
+            }
 
             container.add(buildClassYmlFile(classElement));
-            buildFilesForInnerClasses(classElement, listToAddItems, container);
+            buildFilesForInnerClasses(classElement, tocTypeMap, container);
         }
     }
 

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

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.microsoft.model;
+
+public class KindTitle {
+    private final String elementKind;
+    private final String title;
+
+    public KindTitle(String elementKind, String title) {
+        this.elementKind = elementKind;
+        this.title = title;
+    }
+    public String getElementKind() { return elementKind; }
+    public String getTitle() { return title; }
+}

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

@@ -5,11 +5,13 @@
 
 public class TocItem {
 
-    private final String uid;
-    private final String name;
+    private String uid;
+    private String name;
     private String status;
+    private String heading;
     private List<TocItem> items = new ArrayList<>();
 
+
     public TocItem(String uid, String name) {
         this.uid = uid;
         this.name = name;
@@ -21,6 +23,10 @@ public TocItem(String uid, String name, String status) {
         this.status = status;
     }
 
+    public TocItem(String heading) {
+        this.heading = heading;
+    }
+
     public String getUid() {
         return uid;
     }
@@ -34,4 +40,6 @@ public List<TocItem> getItems() {
     }
 
     public String getStatus() { return status; }
+
+    public String getHeading() { return heading; }
 }

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

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.microsoft.model;
+
+import org.apache.commons.lang3.tuple.Pair;
+
+import javax.lang.model.element.ElementKind;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+
+public class TocTypeMap extends HashMap<String, ArrayList<TocItem>> {
+
+    public TocTypeMap() {
+        this.put(ElementKind.CLASS.name(), new ArrayList<>());
+        this.put(ElementKind.INTERFACE.name(), new ArrayList<>());
+        this.put(ElementKind.ENUM.name(), new ArrayList<>());
+        this.put(ElementKind.ANNOTATION_TYPE.name(), new ArrayList<>());
+        this.put("EXCEPTION", new ArrayList<>());
+    }
+
+    public List<KindTitle> getTitleList() {
+        return List.of(
+                new KindTitle(ElementKind.INTERFACE.name(), "Interfaces"),
+                new KindTitle(ElementKind.CLASS.name(), "Classes"),
+                new KindTitle(ElementKind.ENUM.name(), "Enums"),
+                new KindTitle(ElementKind.ANNOTATION_TYPE.name(),"Annotation Types"),
+                new KindTitle("EXCEPTION", "Exceptions"));
+    }
+}

third_party/docfx-doclet-143274/src/test/java/com/microsoft/build/YmlFilesBuilderTest.java

@@ -1,10 +1,7 @@
 package com.microsoft.build;
 
 import com.google.testing.compile.CompilationRule;
-import com.microsoft.model.MetadataFile;
-import com.microsoft.model.MetadataFileItem;
-import com.microsoft.model.MethodParameter;
-import com.microsoft.model.Syntax;
+import com.microsoft.model.*;
 import com.sun.source.util.DocTrees;
 import jdk.javadoc.doclet.DocletEnvironment;
 import org.apache.commons.lang3.RegExUtils;
@@ -15,6 +12,7 @@
 import org.mockito.Mockito;
 import org.mockito.junit.MockitoJUnitRunner;
 
+import javax.lang.model.element.ElementKind;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.util.Elements;
 import java.io.File;
@@ -217,4 +215,38 @@ public void getJavaReferenceHref(){
         assertEquals(baseURL, result12);
         assertEquals(baseURL, result13);
     }
+
+    @Test
+    public void joinTocTypeItems(){
+        TocTypeMap typeMap = new TocTypeMap();
+        TocItem classToc = new TocItem("uid1", "name1");
+        TocItem interfaceToc = new TocItem("uid2", "name2");
+        TocItem enumToc = new TocItem("uid3", "name3");
+        TocItem annotationToc = new TocItem("uid4", "name4");
+        TocItem exceptionToc = new TocItem("uid5", "name5");
+
+        typeMap.get(ElementKind.CLASS.name()).add(classToc);
+        typeMap.get(ElementKind.INTERFACE.name()).add(interfaceToc);
+        typeMap.get(ElementKind.ENUM.name()).add(enumToc);
+        typeMap.get(ElementKind.ANNOTATION_TYPE.name()).add(annotationToc);
+        typeMap.get("EXCEPTION").add(exceptionToc);
+
+        List<TocItem> tocItems = ymlFilesBuilder.joinTocTypeItems(typeMap);
+
+        assertEquals("Interfaces", tocItems.get(0).getHeading());
+        assertEquals(interfaceToc, tocItems.get(1));
+
+        assertEquals("Classes", tocItems.get(2).getHeading());
+        assertEquals(classToc, tocItems.get(3));
+
+        assertEquals("Enums", tocItems.get(4).getHeading());
+        assertEquals(enumToc, tocItems.get(5));
+
+        assertEquals("Annotation Types", tocItems.get(6).getHeading());
+        assertEquals(annotationToc, tocItems.get(7));
+
+        assertEquals("Exceptions", tocItems.get(8).getHeading());
+        assertEquals(exceptionToc, tocItems.get(9));
+    }
+
 }

third_party/docfx-doclet-143274/src/test/java/com/microsoft/model/TocTypeMapTest.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.microsoft.model;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.mockito.junit.MockitoJUnitRunner;
+
+import java.util.List;
+
+import static org.junit.Assert.*;
+
+@RunWith(MockitoJUnitRunner.class)
+public class TocTypeMapTest {
+    @Test
+    public void elementKindsExistInMap() {
+        TocTypeMap tocTypeMap = new TocTypeMap();
+        List<KindTitle> titleList = tocTypeMap.getTitleList();
+
+        assertEquals("Should include 5 items in list", 5, titleList.size());
+
+        titleList.stream().forEach(kindtitle -> assertNotNull("Element kind should exist in map",
+                tocTypeMap.get(kindtitle.getElementKind())));
+
+        assertNull("Should not include provided key", tocTypeMap.get("FAKE_VALUE"));
+    }
+}

third_party/docfx-doclet-143274/src/test/java/com/microsoft/samples/google/BetaApi.java

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2017, Google Inc.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.microsoft.samples.google;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates a public API that can change at any time, and has no guarantee of API stability and
+ * backward-compatibility.
+ *
+ * <p>
+ * Usage guidelines:
+ * <ol>
+ * <li>This annotation is used only on APIs with public visibility. Internal interfaces should not
+ * use it.</li>
+ * <li>This annotation should only be added to new APIs. Adding it to an existing API is considered
+ * API-breaking.</li>
+ * <li>Removing this annotation from an API gives it stable status, assuming the API doesn't have
+ * other annotations denoting instability.
+ * </ol>
+ */
+@BetaApi
+@Retention(RetentionPolicy.RUNTIME)
+@Target({
+  ElementType.ANNOTATION_TYPE,
+  ElementType.CONSTRUCTOR,
+  ElementType.FIELD,
+  ElementType.METHOD,
+  ElementType.PACKAGE,
+  ElementType.TYPE
+})
+@Documented
+public @interface BetaApi {
+  /**
+   * Context information such as links to a discussion thread, tracking issue, etc.
+   */
+  String value() default "";
+}