From c22c9e1ea217ef28d157af2152f734cbd1e71d86 Mon Sep 17 00:00:00 2001
From: Ann Meng <anmeng@microsoft.com>
Date: Fri, 15 May 2020 13:50:36 +0800
Subject: [PATCH] exclude private and package-private classes during
 documentation

---
 .../com/microsoft/build/YmlFilesBuilder.java  |  2 +-
 .../java/com/microsoft/util/ElementUtil.java  |  3 +++
 .../samples/subpackage/CustomException.java   |  8 ++++++++
 .../samples/subpackage/InternalException.java | 12 +++++++++++
 .../com/microsoft/util/ElementUtilTest.java   | 20 ++++++++++++++-----
 5 files changed, 39 insertions(+), 6 deletions(-)
 create mode 100644 src/test/java/com/microsoft/samples/subpackage/InternalException.java

diff --git a/src/main/java/com/microsoft/build/YmlFilesBuilder.java b/src/main/java/com/microsoft/build/YmlFilesBuilder.java
index 2a5c50c..d247d6a 100644
--- a/src/main/java/com/microsoft/build/YmlFilesBuilder.java
+++ b/src/main/java/com/microsoft/build/YmlFilesBuilder.java
@@ -286,7 +286,7 @@ void addSuperclassAndInterfacesReferences(TypeElement classElement, MetadataFile
 
     void addInnerClassesReferences(TypeElement classElement, MetadataFile classMetadataFile) {
         classMetadataFile.getReferences().addAll(
-                ElementFilter.typesIn(classElement.getEnclosedElements()).stream()
+                ElementFilter.typesIn(elementUtil.extractSortedElements(classElement)).stream()
                         .map(this::buildClassReference)
                         .collect(Collectors.toList()));
     }
diff --git a/src/main/java/com/microsoft/util/ElementUtil.java b/src/main/java/com/microsoft/util/ElementUtil.java
index 0f850ea..85f9b24 100644
--- a/src/main/java/com/microsoft/util/ElementUtil.java
+++ b/src/main/java/com/microsoft/util/ElementUtil.java
@@ -28,7 +28,10 @@ public ElementUtil(String[] excludePackages, String[] excludeClasses) {
 
     public List<TypeElement> extractSortedElements(Element element) {
         // Need to apply sorting, because order of result items for Element.getEnclosedElements() depend on JDK implementation
+        // By default, exclude private and package-private items
+        // todo allow pass parameter for filter items by access modifiers
         return ElementFilter.typesIn(element.getEnclosedElements()).stream()
+            .filter(o -> !isPrivateOrPackagePrivate(o))
             .filter(o -> !matchAnyPattern(excludeClasses, String.valueOf(o.getQualifiedName())))
             .sorted((o1, o2) ->
                 StringUtils.compare(String.valueOf(o1.getSimpleName()), String.valueOf(o2.getSimpleName()))
diff --git a/src/test/java/com/microsoft/samples/subpackage/CustomException.java b/src/test/java/com/microsoft/samples/subpackage/CustomException.java
index 4f7d02a..8c71fd2 100644
--- a/src/test/java/com/microsoft/samples/subpackage/CustomException.java
+++ b/src/test/java/com/microsoft/samples/subpackage/CustomException.java
@@ -14,4 +14,12 @@ public CustomException(String message) {
     public void makeSomething() throws CustomException {
         throw new CustomException("It happened!");
     }
+
+    /**
+     * This is a private class which will not be documented.
+     */
+
+    private class PrivateException {
+        private String message;
+    }
 }
diff --git a/src/test/java/com/microsoft/samples/subpackage/InternalException.java b/src/test/java/com/microsoft/samples/subpackage/InternalException.java
new file mode 100644
index 0000000..a96a249
--- /dev/null
+++ b/src/test/java/com/microsoft/samples/subpackage/InternalException.java
@@ -0,0 +1,12 @@
+package com.microsoft.samples.subpackage;
+
+/**
+ * This is a package-private class which will not be documented.
+ */
+
+class InternalException extends Exception {
+
+    public InternalException(String message) {
+        super(message);
+    }
+}
diff --git a/src/test/java/com/microsoft/util/ElementUtilTest.java b/src/test/java/com/microsoft/util/ElementUtilTest.java
index 4d3780c..0df13b5 100644
--- a/src/test/java/com/microsoft/util/ElementUtilTest.java
+++ b/src/test/java/com/microsoft/util/ElementUtilTest.java
@@ -55,13 +55,23 @@ public void extractPackageElements() {
     public void extractSortedElements() {
         Element element = elements.getPackageElement("com.microsoft.samples.subpackage");
 
-        List<String> result = elementUtil.extractSortedElements(element)
+        List<String> allElements = element.getEnclosedElements()
+                .stream().map(String::valueOf).collect(Collectors.toList());
+
+        // Ensure items to exclude exist.
+        assertThat("Wrong enclosed elements number", allElements.size(), is(6));
+        assertTrue("Unexpected package private class", allElements.contains("com.microsoft.samples.subpackage.InternalException"));
+        assertTrue("Unexpected to-exclude class", allElements.contains("com.microsoft.samples.subpackage.SomeExcludedClass"));
+
+
+        List<String> extractedElements = elementUtil.extractSortedElements(element)
             .stream().map(String::valueOf).collect(Collectors.toList());
 
-        assertThat("Wrong result list size", result.size(), is(4));
-        assertThat("Unexpected first item", result.get(0), is("com.microsoft.samples.subpackage.CustomException"));
-        assertThat("Unexpected second item", result.get(1), is("com.microsoft.samples.subpackage.Display"));
-        assertThat("Unexpected third item", result.get(2), is("com.microsoft.samples.subpackage.Person"));
+        // Verify filtered and sorted result
+        assertThat("Wrong result list size", extractedElements.size(), is(4));
+        assertThat("Unexpected first item", extractedElements.get(0), is("com.microsoft.samples.subpackage.CustomException"));
+        assertThat("Unexpected second item", extractedElements.get(1), is("com.microsoft.samples.subpackage.Display"));
+        assertThat("Unexpected third item", extractedElements.get(2), is("com.microsoft.samples.subpackage.Person"));
     }
 
     @Test