More javadoc and query validation

Added javadoc for each value of Fork search mode enum.
Made passing UNKNOWN to visibility() throw a GHException. UNKNOWN a placeholder and should never be
passed into any method in the API.

Author: bitwiseman

src/main/java/org/kohsuke/github/GHRepository.java

@@ -727,7 +727,20 @@ public boolean isPrivate() {
      * Visibility of a repository.
      */
     public enum Visibility {
-        PUBLIC, INTERNAL, PRIVATE, UNKNOWN;
+        PUBLIC,
+        INTERNAL,
+        PRIVATE,
+
+        /**
+         * Placeholder for unexpected data values.
+         *
+         * This avoids throwing exceptions during data binding or reading when the list of allowed values returned from
+         * GitHub is expanded.
+         *
+         * Do not pass this value to any methods. If this value is returned during a request, check the log output and
+         * report an issue for the missing value.
+         */
+        UNKNOWN;
 
         public static Visibility from(String value) {
             return EnumUtils.getNullableEnumOrDefault(Visibility.class, value, Visibility.UNKNOWN);

src/main/java/org/kohsuke/github/GHRepositorySearchBuilder.java

@@ -55,10 +55,16 @@ public GHRepositorySearchBuilder forks(String v) {
     /**
      * Searching in forks
      *
-     * By default, forks are not shown in search results. Forks are only indexed for code search when they have more
-     * stars than the parent repository. You will not be able to search the code in a fork that has less stars than its
-     * parent. To show forks with more stars than the parent repository in code search results, add
-     * Fork.ALL_INCLUDING_FORKS or Fork.FORKS_ONLY.
+     * The default search mode is {@link Fork#PARENT_ONLY}. In that mode, forks are not included in search results.
+     *
+     * <p>
+     * Passing {@link Fork#PARENT_AND_FORKS} or {@link Fork#FORKS_ONLY} will show results from forks, but only if they
+     * have more stars than the parent repository.
+     *
+     * <p>
+     * IMPORTANT: Regardless of this setting, no search results will ever be returned for forks with equal or fewer
+     * stars than the parent repository. Forks with less stars than the parent repository are not included in the index
+     * for code searching.
      *
      * @param fork
      *            search mode for forks
@@ -71,7 +77,7 @@ public GHRepositorySearchBuilder forks(String v) {
      *
      */
     public GHRepositorySearchBuilder fork(Fork fork) {
-        if (fork == Fork.DEFAULT) {
+        if (Fork.PARENT_ONLY.equals(fork)) {
             this.terms.removeIf(term -> term.contains("fork:"));
             return this;
         }
@@ -82,21 +88,21 @@ public GHRepositorySearchBuilder fork(Fork fork) {
     /**
      * Search by repository visibility
      *
-     * If visibility param value equals to GHRepository.Visibility.UNKNOWN, this search criteria will be ignored.
-     *
      * @param visibility
      *            repository visibility
      *
      * @return the gh repository search builder
-     *
+     * @throws GHException
+     *             if {@link GHRepository.Visibility#UNKNOWN} is passed. UNKNOWN is a placeholder for unexpected values
+     *             encountered when reading data.
      * @see <a href=
      *      "https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-for-repositories#search-by-repository-visibility">Search
      *      by repository visibility</a>
-     *
      */
     public GHRepositorySearchBuilder visibility(GHRepository.Visibility visibility) {
         if (visibility == GHRepository.Visibility.UNKNOWN) {
-            return this;
+            throw new GHException(
+                    "UNKNOWN is a placeholder for unexpected values encountered when reading data. It cannot be passed as a search parameter.");
         }
 
         return q("is:" + visibility);
@@ -211,15 +217,30 @@ public enum Sort {
     }
 
     /**
-     * The enum Fork.
-     *
-     * By default, forks are not shown in search results. Forks are only indexed for code search when they have more
-     * stars than the parent repository. You will not be able to search the code in a fork that has less stars than its
-     * parent. To show forks with more stars than the parent repository in code search results, add
-     * Fork.ALL_INCLUDING_FORKS or Fork.FORKS_ONLY.
+     * The enum for Fork search mode
      */
     public enum Fork {
-        ALL_INCLUDING_FORKS("true"), FORKS_ONLY("only"), DEFAULT("ignore");
+
+        /**
+         * Search in the parent repository and in forks with more stars than the parent repository.
+         *
+         * Forks with the same or fewer stars than the parent repository are still ignored.
+         */
+        PARENT_AND_FORKS("true"),
+
+        /**
+         * Search only in forks with more stars than the parent repository.
+         *
+         * The parent repository is ignored. If no forks have more stars than the parent, no results will be returned.
+         */
+        FORKS_ONLY("only"),
+
+        /**
+         * (Default) Search only the parent repository.
+         *
+         * Forks are ignored.
+         */
+        PARENT_ONLY("");
 
         private String filterMode;
         Fork(String mode) {

src/test/java/org/kohsuke/github/GHRepositoryTest.java

@@ -20,6 +20,7 @@
 
 import static org.hamcrest.Matchers.*;
 import static org.hamcrest.core.IsInstanceOf.instanceOf;
+import static org.junit.Assert.assertThrows;
 import static org.kohsuke.github.GHVerification.Reason.*;
 
 /**
@@ -422,7 +423,7 @@ public void searchAllPublicAndForkedRepos() throws IOException {
         PagedSearchIterable<GHRepository> list = gitHub.searchRepositories()
                 .user("t0m4uk1991")
                 .visibility(GHRepository.Visibility.PUBLIC)
-                .fork(GHRepositorySearchBuilder.Fork.ALL_INCLUDING_FORKS)
+                .fork(GHRepositorySearchBuilder.Fork.PARENT_AND_FORKS)
                 .list();
         List<GHRepository> u = list.toList();
         assertThat(u.size(), is(14));
@@ -446,8 +447,11 @@ public void searchForPublicForkedOnlyRepos() throws IOException {
     @Test
     public void ghRepositorySearchBuilderIgnoresUnknownVisibility() {
         GHRepositorySearchBuilder ghRepositorySearchBuilder;
-        ghRepositorySearchBuilder = new GHRepositorySearchBuilder(gitHub).visibility(Visibility.UNKNOWN);
-        assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("is:")).count(), is(0L));
+
+        GHException exception = assertThrows(GHException.class,
+                () -> new GHRepositorySearchBuilder(gitHub).visibility(Visibility.UNKNOWN));
+        assertThat(exception.getMessage(),
+                startsWith("UNKNOWN is a placeholder for unexpected values encountered when reading data."));
 
         ghRepositorySearchBuilder = new GHRepositorySearchBuilder(gitHub).visibility(Visibility.PUBLIC);
         assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("is:")).count(), is(1L));
@@ -462,15 +466,15 @@ public void ghRepositorySearchBuilderIgnoresUnknownVisibility() {
     @Test
     public void ghRepositorySearchBuilderForkDefaultResetForksSearchTerms() {
         GHRepositorySearchBuilder ghRepositorySearchBuilder = new GHRepositorySearchBuilder(gitHub);
-        ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.ALL_INCLUDING_FORKS);
+        ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.PARENT_AND_FORKS);
         assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:true")).count(), is(1L));
         assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:")).count(), is(1L));
 
         ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.FORKS_ONLY);
         assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:only")).count(), is(1L));
         assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:")).count(), is(2L));
 
-        ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.DEFAULT);
+        ghRepositorySearchBuilder = ghRepositorySearchBuilder.fork(GHRepositorySearchBuilder.Fork.PARENT_ONLY);
         assertThat(ghRepositorySearchBuilder.terms.stream().filter(item -> item.contains("fork:")).count(), is(0L));
     }