Omit internal results from docs search unless requested.

Author: Saladoc

src/main/java/org/javacord/bot/commands/DocsCommand.java

@@ -14,16 +14,33 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.util.Arrays;
+import java.util.Collections;
 import java.util.Comparator;
+import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Set;
+import java.util.concurrent.CompletableFuture;
 import java.util.stream.Collectors;
 
 /**
  * The !docs command which is used to show links to Javacord's JavaDocs.
  */
 public class DocsCommand implements CommandExecutor {
 
+    /**
+     * The parameters that indicate searching for class names only.
+     */
+    private static final Set<String> classParams = new HashSet<>(Arrays.asList("classes", "class", "c"));
+    /**
+     * The parameters that indicate searching for method names only.
+     */
+    private static final Set<String> methodParams = new HashSet<>(Arrays.asList("methods", "method", "m"));
+    /**
+     * The parameters that indicate also searching internal packages and the core docs.
+     */
+    private static final Set<String> includeAllParams = new HashSet<>(Arrays.asList("all", "a"));
+    
     /**
      * Executes the {@code !docs} command.
      *
@@ -42,16 +59,21 @@ public void onCommand(TextChannel channel, String[] args) throws IOException {
                         .addField("Latest release version", "https://docs.javacord.org/api/v/latest")
                         .addField("Latest snapshot", "https://docs.javacord.org/api/build/latest")
                         .addField("Hint", "You can search the docs using `!docs [method|class] <search>`");
-            } else { // Search
-                if (args[0].matches("(classes|class|c)")) { // Search for a class
-                    String searchString = String.join(" ", Arrays.copyOfRange(args, 1, args.length));
-                    populateClasses(channel.getApi(), embed, searchString);
-                } else if (args[0].matches("(methods|method|m)")) { // Search for a method
-                    String searchString = String.join(" ", Arrays.copyOfRange(args, 1, args.length));
-                    populateMethods(channel.getApi(), embed, searchString);
+            } else if (args.length == 1) { // Basic search - methods without internals
+                populateMethods(channel.getApi(), embed, args[0], false);
+            } else { // Extended search
+                if (classParams.contains(args[0])) { // Search for a class
+                    boolean searchAll = args.length > 2 && includeAllParams.contains(args[1]);
+                    String searchString = String.join(" ", Arrays.copyOfRange(args, searchAll ? 2 : 1, args.length));
+                    populateClasses(channel.getApi(), embed, searchString, searchAll);
+                } else if (methodParams.contains(args[0])) { // Search for a method
+                    boolean searchAll = args.length > 2 && includeAllParams.contains(args[1]);
+                    String searchString = String.join(" ", Arrays.copyOfRange(args, searchAll ? 2 : 1, args.length));
+                    populateMethods(channel.getApi(), embed, searchString, searchAll);
                 } else { // Search for a method
-                    String searchString = String.join(" ", args);
-                    populateMethods(channel.getApi(), embed, searchString);
+                    boolean searchAll = includeAllParams.contains(args[0]);
+                    String searchString = String.join(" ", Arrays.copyOfRange(args, searchAll ? 1 : 0, args.length));
+                    populateMethods(channel.getApi(), embed, searchString, searchAll);
                 }
             }
             channel.sendMessage(embed).join();
@@ -70,10 +92,22 @@ public void onCommand(TextChannel channel, String[] args) throws IOException {
      * @param embed        The embed to populate.
      * @param searchString A search string.
      */
-    private void populateMethods(DiscordApi api, EmbedBuilder embed, String searchString) {
-        Map<String, List<JavadocMethod>> methods = new JavadocParser(api, JavadocParser.getLatestJavaDocs(api).join())
-                .getMethods().join().stream()
+    private void populateMethods(DiscordApi api, EmbedBuilder embed, String searchString, boolean includeAll) {
+        CompletableFuture<Set<JavadocMethod>> apiMethods = JavadocParser.getLatestJavaDocs(api)
+                .thenApply(urlString -> new JavadocParser(api, urlString))
+                .thenCompose(JavadocParser::getMethods);
+        CompletableFuture<Set<JavadocMethod>> coreMethods = (includeAll)
+                ? JavadocParser.getLatestCoreJavaDocs(api)
+                .thenApply(urlString -> new JavadocParser(api, urlString))
+                .thenCompose(JavadocParser::getMethods)
+                : CompletableFuture.completedFuture(Collections.emptySet());
+
+        Map<String, List<JavadocMethod>> methods = apiMethods.thenCombine(coreMethods, this::unionOf).join().stream()
                 .filter(method -> method.getFullName().toLowerCase().contains(searchString.toLowerCase()))
+                .filter(method -> {
+                    String packageName = method.getPackageName();
+                    return includeAll || !(packageName.endsWith(".internal") || packageName.contains(".internal."));
+                })
                 .sorted(Comparator.comparingInt(method -> method.getName().length()))
                 .collect(Collectors.groupingBy(JavadocMethod::getClassName));
 
@@ -115,17 +149,47 @@ private void populateMethods(DiscordApi api, EmbedBuilder embed, String searchSt
         }
     }
 
+    /**
+     * Union operation for sets.
+     *
+     * @param set1 First set.
+     * @param set2 Second set.
+     * @param <T>  Type of set content.
+     * @return The union of the two sets.
+     */
+    private <T> Set<T> unionOf(Set<T> set1, Set<T> set2) {
+        if (set2.isEmpty()) {
+            return set1;
+        } else {
+            Set<T> union = new HashSet<>(set1);
+            union.addAll(set2);
+            return union;
+        }
+    }
+
     /**
      * Populates the classes field inside the given embed.
      *
      * @param api          A discord api instance.
      * @param embed        The embed to populate.
      * @param searchString A search string.
      */
-    private void populateClasses(DiscordApi api, EmbedBuilder embed, String searchString) {
-        List<JavadocClass> classes = new JavadocParser(api, JavadocParser.getLatestJavaDocs(api).join())
-                .getClasses().join().stream()
+    private void populateClasses(DiscordApi api, EmbedBuilder embed, String searchString, boolean includeAll) {
+        CompletableFuture<Set<JavadocClass>> apiClasses = JavadocParser.getLatestJavaDocs(api)
+                .thenApply(urlString -> new JavadocParser(api, urlString))
+                .thenCompose(JavadocParser::getClasses);
+        CompletableFuture<Set<JavadocClass>> coreClasses = (includeAll)
+                ? JavadocParser.getLatestCoreJavaDocs(api)
+                .thenApply(urlString -> new JavadocParser(api, urlString))
+                .thenCompose(JavadocParser::getClasses)
+                : CompletableFuture.completedFuture(Collections.emptySet());
+
+        List<JavadocClass> classes = apiClasses.thenCombine(coreClasses, this::unionOf).join().stream()
                 .filter(clazz -> clazz.getName().toLowerCase().contains(searchString.toLowerCase()))
+                .filter(clazz -> {
+                    String packageName = clazz.getPackageName();
+                    return includeAll || !(packageName.endsWith(".internal") || packageName.contains(".internal."));
+                })
                 .sorted(Comparator.comparingInt(clazz -> clazz.getName().length()))
                 .collect(Collectors.toList());
 
@@ -138,19 +202,22 @@ private void populateClasses(DiscordApi api, EmbedBuilder embed, String searchSt
         StringBuilder strBuilder = new StringBuilder();
         int counter = 0;
         for (JavadocClass clazz : classes) {
+            if (strBuilder.length() > 0) {
+                strBuilder.append(", ");
+            }
             strBuilder.append("[")
                     .append(clazz.getName())
                     .append("](")
                     .append(clazz.getFullUrl())
-                    .append("), ");
+                    .append(")");
             counter++;
             if (strBuilder.length() > 1950) { // Prevent hitting the description size limit
                 break;
             }
         }
 
         if (classes.size() - counter > 0) {
-            strBuilder.append("and ").append(classes.size() - counter).append(" more ...");
+            strBuilder.append("\nand ").append(classes.size() - counter).append(" more ...");
         }
 
         embed.setDescription(strBuilder.toString());

src/main/java/org/javacord/bot/util/javadoc/parser/JavadocParser.java

@@ -43,10 +43,24 @@ public JavadocParser(DiscordApi api, String url) {
      * @return The latest JavaDoc link.
      */
     public static CompletableFuture<String> getLatestJavaDocs(DiscordApi api) {
+        return getJavadocUrl(api, "https://docs.javacord.org/api/");
+    }
+
+    /**
+     * Gets the latest core JavaDoc link.
+     *
+     * @param api A discord api instance.
+     * @return The latest core JavaDoc link.
+     */
+    public static CompletableFuture<String> getLatestCoreJavaDocs(DiscordApi api) {
+        return getJavadocUrl(api, "https://docs.javacord.org/core/");
+    }
+
+    private static CompletableFuture<String> getJavadocUrl(DiscordApi api, String url) {
         return CompletableFuture.supplyAsync(() -> {
             try {
                 Request request = new Request.Builder()
-                        .url("https://docs.javacord.org/api/")
+                        .url(url)
                         .build();
 
                 try (Response response = client.newCall(request).execute()) {