[JENKINS-43507] Javadocs

jenkinsci · Jun 19, 2017 · da85c3797caaf35ee0ef01db2d738bb3ddd2e299 · da85c37
1 parent 19b1697
commit da85c3797caaf35ee0ef01db2d738bb3ddd2e299
Unified Split

Showing with 96 additions and 9 deletions.

+94 −7 src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigator.java

+2 −2 src/test/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorTraitsTest.java
diff --git a/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigator.java b/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigator.java
@@ -75,6 +75,7 @@
 import jenkins.scm.impl.trait.RegexSCMSourceFilterTrait;
 import jenkins.scm.impl.trait.Selection;
 import jenkins.scm.impl.trait.WildcardSCMHeadFilterTrait;
+  
+import net.jcip.annotations.GuardedBy;
 import org.apache.commons.lang.StringUtils;
 import org.jenkins.ui.icon.Icon;
 import org.jenkins.ui.icon.IconSet;
@@ -226,7 +227,7 @@ public GitHubSCMNavigator(String apiUri, String repoOwner, String scanCredential
        this(repoOwner);
        setCredentialsId(scanCredentialsId);
        setApiUri(apiUri);
-  
-        if (checkoutCredentialsId != null && !GitHubSCMSource.DescriptorImpl.SAME.equals(checkoutCredentialsId)) {
+  
+        if (checkoutCredentialsId != null && !DescriptorImpl.SAME.equals(checkoutCredentialsId)) {
            traits.add(new SSHCheckoutTrait(checkoutCredentialsId));
        }
    }
@@ -351,7 +352,7 @@ private Object readResolve() {
                }
                traits.add(new ForkPullRequestDiscoveryTrait(s, new ForkPullRequestDiscoveryTrait.TrustContributors()));
            }
-  
-            if (!GitHubSCMSource.DescriptorImpl.SAME.equals(checkoutCredentialsId)) {
+  
+            if (!DescriptorImpl.SAME.equals(checkoutCredentialsId)) {
                traits.add(new SSHCheckoutTrait(checkoutCredentialsId));
            }
            if ((includes != null && !"*".equals(includes)) || (excludes != null && !"".equals(excludes))) {
@@ -787,7 +788,7 @@ public String getCheckoutCredentialsId() {
                );
            }
        }
-  
-        return GitHubSCMSource.DescriptorImpl.SAME;
+  
+        return DescriptorImpl.SAME;
    }
    /**
@@ -1276,19 +1277,45 @@ public SCMNavigator newInstance(String name) {
            };
        }
+  
+        /**
+  
+         * Validates the selected credentials.
+  
+         *
+  
+         * @param context       the context.
+  
+         * @param apiUri        the end-point.
+  
+         * @param credentialsId the credentials.
+  
+         * @return validation results.
+  
+         * @since 2.2.0
+  
+         */
        @Restricted(NoExternalUse.class) // stapler
        public FormValidation doCheckCredentialsId(@CheckForNull @AncestorInPath Item context,
                                                       @QueryParameter String apiUri,
                                                       @QueryParameter String credentialsId) {
            return Connector.checkScanCredentials(context, apiUri, credentialsId);
        }
-  
-        @Restricted(NoExternalUse.class)
+  
+        /**
+  
+         * Populates the drop-down list of credentials.
+  
+         *
+  
+         * @param context the context.
+  
+         * @param apiUri  the end-point.
+  
+         * @return the drop-down list.
+  
+         * @since 2.2.0
+  
+         */
+  
+        @Restricted(NoExternalUse.class) // stapler
        public ListBoxModel doFillCredentialsIdItems(@CheckForNull @AncestorInPath Item context,
                                                         @QueryParameter String apiUri) {
            return Connector.listScanCredentials(context, apiUri);
        }
+  
+        /**
+  
+         * Legacy method.
+  
+         *
+  
+         * @param context the context.
+  
+         * @param apiUri  the endpoint.
+  
+         * @param scanCredentialsId the scan credentials.
+  
+         * @return the {@link ListBoxModel}
+  
+         * @deprecated use {@link #doCheckCredentialsId(Item, String, String)}
+  
+         */
        @Deprecated
        @Restricted(NoExternalUse.class)
        public FormValidation doCheckScanCredentialsId(@CheckForNull @AncestorInPath Item context,
@@ -1297,12 +1324,26 @@ public FormValidation doCheckScanCredentialsId(@CheckForNull @AncestorInPath Ite
            return doCheckCredentialsId(context, apiUri, scanCredentialsId);
        }
+  
+        /**
+  
+         * Legacy method.
+  
+         *
+  
+         * @param context the context.
+  
+         * @param apiUri  the endpoint.
+  
+         * @return the {@link ListBoxModel}
+  
+         * @deprecated use {@link #doFillCredentialsIdItems(Item, String)}
+  
+         */
        @Deprecated
        @Restricted(NoExternalUse.class)
+  
+        @RestrictedSince("2.2.0")
        public ListBoxModel doFillScanCredentialsIdItems(@CheckForNull @AncestorInPath Item context, @QueryParameter String apiUri) {
            return doFillCredentialsIdItems(context, apiUri);
        }
+  
+        /**
+  
+         * Returns the available GitHub endpoint items.
+  
+         *
+  
+         * @return the available GitHub endpoint items.
+  
+         */
        @Restricted(NoExternalUse.class) // stapler
        @SuppressWarnings("unused") // stapler
        public ListBoxModel doFillApiUriItems() {
@@ -1314,11 +1355,23 @@ public ListBoxModel doFillApiUriItems() {
            return result;
        }
+  
+        /**
+  
+         * Returns {@code true} if there is more than one GitHub endpoint configured, and consequently the UI should
+  
+         * provide the ability to select the endpoint.
+  
+         *
+  
+         * @return {@code true} if there is more than one GitHub endpoint configured.
+  
+         */
        @SuppressWarnings("unused") // jelly
        public boolean isApiUriSelectable() {
            return !GitHubConfiguration.get().getEndpoints().isEmpty();
        }
+  
+        /**
+  
+         * Returns the {@link SCMTraitDescriptor} instances grouped into categories.
+  
+         *
+  
+         * @return the categorized list of {@link SCMTraitDescriptor} instances.
+  
+         * @since 2.2.0
+  
+         */
        @SuppressWarnings("unused") // jelly
        public List<NamedArrayList<? extends SCMTraitDescriptor<?>>> getTraitsDescriptorLists() {
            List<SCMTraitDescriptor<?>> all = new ArrayList<>();
@@ -1432,24 +1485,47 @@ public boolean test(SCMTraitDescriptor<?> scmTraitDescriptor) {
     * A {@link SCMNavigatorRequest.Witness} that counts how many sources have been observed.
     */
    private static class WitnessImpl implements SCMNavigatorRequest.Witness {
+  
+        /**
+  
+         * The count of repositories matches.
+  
+         */
+  
+        @GuardedBy("this")
        private int count;
+  
+        /**
+  
+         * The listener to log to.
+  
+         */
+  
+        @NonNull
        private final TaskListener listener;
-  
-        public WitnessImpl(TaskListener listener) {
+  
+        /**
+  
+         * Constructor.
+  
+         *
+  
+         * @param listener the listener to log to.
+  
+         */
+  
+        public WitnessImpl(@NonNull TaskListener listener) {
            this.listener = listener;
        }
+  
+        /**
+  
+         * {@inheritDoc}
+  
+         */
        @Override
        public void record(@NonNull String name, boolean isMatch) {
            if (isMatch) {
                listener.getLogger().format("Proposing %s%n", name);
-  
-                count++;
+  
+                synchronized (this) {
+  
+                    count++;
+  
+                }
            } else {
                listener.getLogger().format("Ignoring %s%n", name);
            }
        }
-  
-        public int getCount() {
+  
+        /**
+  
+         * Returns the count of repositories matches.
+  
+         *
+  
+         * @return the count of repositories matches.
+  
+         */
+  
+        public synchronized int getCount() {
            return count;
        }
    }
@@ -1458,12 +1534,23 @@ public int getCount() {
     * Our {@link SCMNavigatorRequest.SourceLambda}.
     */
    private class SourceFactory implements SCMNavigatorRequest.SourceLambda {
+  
+        /**
+  
+         * The request.
+  
+         */
        private final GitHubSCMNavigatorRequest request;
+  
+        /**
+  
+         * Constructor.
+  
+         *
+  
+         * @param request the request to decorate {@link SCMSource} instances with.
+  
+         */
        public SourceFactory(GitHubSCMNavigatorRequest request) {
            this.request = request;
        }
+  
+        /**
+  
+         * {@inheritDoc}
+  
+         */
        @NonNull
        @Override
        public SCMSource create(@NonNull String name) {

diff --git a/src/test/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorTraitsTest.java b/src/test/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorTraitsTest.java
@@ -1625,14 +1625,14 @@ public void given__legacyCode__when__setPattern_custom__then__patternSetAndTrait
    @Test
    public void given__legacyCode__when__checkoutCredentials_SAME__then__noTraitAdded() {
        GitHubSCMNavigator instance = new GitHubSCMNavigator(null, "test", "scan", GitHubSCMSource.DescriptorImpl.SAME);
-  
-        assertThat(instance.getCheckoutCredentialsId(), is(GitHubSCMSource.DescriptorImpl.SAME));
+  
+        assertThat(instance.getCheckoutCredentialsId(), is(GitHubSCMNavigator.DescriptorImpl.SAME));
        assertThat(instance.getTraits(), not(Matchers.<SCMTrait<?>>hasItem(instanceOf(SSHCheckoutTrait.class))));
    }
    @Test
    public void given__legacyCode__when__checkoutCredentials_null__then__noTraitAdded() {
        GitHubSCMNavigator instance = new GitHubSCMNavigator(null, "test", "scan", null);
-  
-        assertThat(instance.getCheckoutCredentialsId(), is(GitHubSCMSource.DescriptorImpl.SAME));
+  
+        assertThat(instance.getCheckoutCredentialsId(), is(GitHubSCMNavigator.DescriptorImpl.SAME));
        assertThat(instance.getTraits(), not(Matchers.<SCMTrait<?>>hasItem(instanceOf(SSHCheckoutTrait.class))));
    }