[JENKINS-43507] Documentation and formatting

jenkinsci · Jun 19, 2017 · cbdb2bd016fe735f34e8453cda6c0642c3da545e · cbdb2bd
1 parent 642695b
commit cbdb2bd016fe735f34e8453cda6c0642c3da545e
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
@@ -1,7 +1,7 @@
 /*
 * The MIT License
 *
-  
- * Copyright 2015 CloudBees, Inc.
+  
+ * Copyright 2015-2017 CloudBees, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal

diff --git a/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorContext.java b/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorContext.java
@@ -1,11 +1,42 @@
+  
+/*
+  
+ * The MIT License
+  
+ *
+  
+ * Copyright (c) 2017, CloudBees, Inc.
+  
+ *
+  
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+  
+ * of this software and associated documentation files (the "Software"), to deal
+  
+ * in the Software without restriction, including without limitation the rights
+  
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  
+ * copies of the Software, and to permit persons to whom the Software is
+  
+ * furnished to do so, subject to the following conditions:
+  
+ *
+  
+ * The above copyright notice and this permission notice shall be included in
+  
+ * all copies or substantial portions of the Software.
+  
+ *
+  
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+  
+ * THE SOFTWARE.
+  
+ */
 package org.jenkinsci.plugins.github_branch_source;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import jenkins.scm.api.SCMNavigator;
 import jenkins.scm.api.SCMSourceObserver;
 import jenkins.scm.api.trait.SCMNavigatorContext;
+  
+/**
+  
+ * The {@link SCMNavigatorContext} for GitHub.
+  
+ *
+  
+ * @since 2.2.0
+  
+ */
 public class GitHubSCMNavigatorContext extends SCMNavigatorContext<GitHubSCMNavigatorContext, GitHubSCMNavigatorRequest> {
+  
+    /**
+  
+     * {@inheritDoc}
+  
+     */
    @NonNull
    @Override
    public GitHubSCMNavigatorRequest newRequest(@NonNull SCMNavigator navigator, @NonNull SCMSourceObserver observer) {

diff --git a/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorRequest.java b/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMNavigatorRequest.java
@@ -1,14 +1,48 @@
+  
+/*
+  
+ * The MIT License
+  
+ *
+  
+ * Copyright (c) 2017, CloudBees, Inc.
+  
+ *
+  
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+  
+ * of this software and associated documentation files (the "Software"), to deal
+  
+ * in the Software without restriction, including without limitation the rights
+  
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  
+ * copies of the Software, and to permit persons to whom the Software is
+  
+ * furnished to do so, subject to the following conditions:
+  
+ *
+  
+ * The above copyright notice and this permission notice shall be included in
+  
+ * all copies or substantial portions of the Software.
+  
+ *
+  
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+  
+ * THE SOFTWARE.
+  
+ */
 package org.jenkinsci.plugins.github_branch_source;
 import edu.umd.cs.findbugs.annotations.NonNull;
 import jenkins.scm.api.SCMNavigator;
 import jenkins.scm.api.SCMSourceObserver;
-  
-import jenkins.scm.api.trait.SCMNavigatorContext;
 import jenkins.scm.api.trait.SCMNavigatorRequest;
+  
+/**
+  
+ * The {@link SCMNavigatorRequest} for GitHub.
+  
+ *
+  
+ * @since 2.2.0
+  
+ */
 public class GitHubSCMNavigatorRequest extends SCMNavigatorRequest {
-  
-    public GitHubSCMNavigatorRequest(@NonNull SCMNavigator source,
-  
-                                        @NonNull SCMNavigatorContext<?, ?> context,
+  
+    /**
+  
+     * Constructor.
+  
+     *
+  
+     * @param source   the source.
+  
+     * @param context  the context.
+  
+     * @param observer the observer.
+  
+     */
+  
+    protected GitHubSCMNavigatorRequest(@NonNull SCMNavigator source,
+  
+                                        @NonNull GitHubSCMNavigatorContext context,
                                        @NonNull SCMSourceObserver observer) {
        super(source, context, observer);
    }

diff --git a/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource.java b/src/main/java/org/jenkinsci/plugins/github_branch_source/GitHubSCMSource.java
@@ -1,7 +1,7 @@
 /*
 * The MIT License
 *
-  
- * Copyright 2015-2016 CloudBees, Inc.
+  
+ * Copyright 2015-2017 CloudBees, Inc.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
@@ -141,44 +141,105 @@
     */
    private static final Object pullRequestSourceMapLock = new Object();
-  
-    @CheckForNull
+  
+    //////////////////////////////////////////////////////////////////////
+  
+    // Configuration fields
+  
+    //////////////////////////////////////////////////////////////////////
+  
+
+  
+    /**
+  
+     * The GitHub end-point or {@code null} if {@link #GITHUB_URL} is implied.
+  
+     */
+  
+    @CheckForNull // TODO migrate to non-null with configuration of GITHUB_URL by default
    private String apiUri;
-  
-    /** Credentials for GitHub API; currently only supports username/password (personal access token). */
+  
+    /**
+  
+     * Credentials for GitHub API; currently only supports username/password (personal access token).
+  
+     * @since 2.2.0
+  
+     */
    @CheckForNull
    private String credentialsId;
+  
+    /**
+  
+     * The repository owner.
+  
+     */
+  
+    @NonNull
    private final String repoOwner;
+  
+    /**
+  
+     * The repository
+  
+     */
+  
+    @NonNull
    private final String repository;
+  
+    /**
+  
+     * The behaviours to apply to this source.
+  
+     * @since 2.2.0
+  
+     */
    @NonNull
    private List<SCMSourceTrait> traits;
+  
+    //////////////////////////////////////////////////////////////////////
+  
+    // Legacy Configuration fields
+  
+    //////////////////////////////////////////////////////////////////////
+  
+
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient String scanCredentialsId;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient String checkoutCredentialsId;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private String includes;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private String excludes;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient Boolean buildOriginBranch;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient Boolean buildOriginBranchWithPR;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient Boolean buildOriginPRMerge;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient Boolean buildOriginPRHead;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient Boolean buildForkPRMerge;
+  
+    /**
+  
+     * Legacy field.
+  
+     */
    @Deprecated
    private transient Boolean buildForkPRHead;
+  
+    //////////////////////////////////////////////////////////////////////
+  
+    // Run-time cached state
+  
+    //////////////////////////////////////////////////////////////////////
+  
+
    /**
     * Cache of the official repository HTML URL as reported by {@link GitHub#getRepository(String)}.
     */
+  
+    @CheckForNull
    private transient URL repositoryUrl;
    /**
     * The collaborator names used to determine if pull requests are from trusted authors
@@ -213,17 +274,37 @@
    @CheckForNull // normally null except during a migration from 1.x
    private transient /*effectively final*/ Map<Integer,PullRequestSource> pullRequestSourceMap;
+  
+    /**
+  
+     * Constructor, defaults to {@link #GITHUB_URL} as the end-point, and anonymous access, does not default any
+  
+     * {@link SCMSourceTrait} behaviours.
+  
+     *
+  
+     * @param repoOwner the repository owner.
+  
+     * @param repository the repository name.
+  
+     * @since 2.2.0
+  
+     */
    @DataBoundConstructor
-  
-    public GitHubSCMSource(String repoOwner, String repository) {
+  
+    public GitHubSCMSource(@NonNull String repoOwner, @NonNull String repository) {
        this.repoOwner = repoOwner;
        this.repository = repository;
        pullRequestMetadataCache = new ConcurrentHashMap<>();
        pullRequestContributorCache = new ConcurrentHashMap<>();
        this.traits = new ArrayList<>(((DescriptorImpl) getDescriptor()).getTraitDefaults());
    }
+  
+    /**
+  
+     * Legacy constructor.
+  
+     * @param id the source id.
+  
+     * @param apiUri the GitHub endpoint.
+  
+     * @param checkoutCredentialsId the checkout credentials id or {@link DescriptorImpl#SAME} or
+  
+     * {@link DescriptorImpl#ANONYMOUS}.
+  
+     * @param scanCredentialsId the scan credentials id or {@code null}.
+  
+     * @param repoOwner the repository owner.
+  
+     * @param repository the repository name.
+  
+     */
    @Deprecated
-  
-    public GitHubSCMSource(String id, String apiUri, String checkoutCredentialsId, String scanCredentialsId, String repoOwner, String repository) {
+  
+    public GitHubSCMSource(@CheckForNull String id, @CheckForNull String apiUri, @NonNull String checkoutCredentialsId,
+  
+                           @CheckForNull String scanCredentialsId, @NonNull String repoOwner,
+  
+                           @NonNull String repository) {
        this(repoOwner, repository);
        setId(id);
        setApiUri(apiUri);
@@ -238,53 +319,89 @@ public GitHubSCMSource(String id, String apiUri, String checkoutCredentialsId, S
        }
    }
-  
-    @Deprecated
-  
-    public GitHubSCMSource(String id, String repoOwner, String repository) {
-  
-        this(repoOwner, repository);
-  
-        setId(id);
-  
-    }
-  
-
-  
-    @CheckForNull
+  
+    /**
+  
+     * Returns the GitHub API end-point or {@code null} if {@link #GITHUB_URL}.
+  
+     *
+  
+     * @return the GitHub API end-point or {@code null} if {@link #GITHUB_URL}.
+  
+     */
+  
+    @CheckForNull // TODO switch to NonNull
    public String getApiUri() {
        return apiUri;
    }
+  
+    /**
+  
+     * Sets the GitHub API end-point.
+  
+     *
+  
+     * @param apiUri the GitHub API end-point or {@code null} if {@link #GITHUB_URL}.
+  
+     * @since 2.2.0
+  
+     */
    @DataBoundSetter
-  
-    public void setApiUri(String apiUri) {
+  
+    public void setApiUri(@CheckForNull String apiUri) {
        this.apiUri = Util.fixEmptyAndTrim(apiUri);
    }
+  
+    /**
+  
+     * Gets the credentials used to access the GitHub REST API (also used as the default credentials for checking out
+  
+     * sources.
+  
+     * @return the credentials used to access the GitHub REST API or {@code null} to access anonymously
+  
+     */
+  
+    @Override
    @CheckForNull
    public String getCredentialsId() {
        return credentialsId;
    }
+  
+    /**
+  
+     * Sets the credentials used to access the GitHub REST API (also used as the default credentials for checking out
+  
+     * sources.
+  
+     *
+  
+     * @param credentialsId the credentials used to access the GitHub REST API or {@code null} to access anonymously
+  
+     * @since 2.2.0
+  
+     */
    @DataBoundSetter
-  
-    public void setCredentialsId(@CheckForNull String scanCredentialsId) {
-  
-        this.credentialsId = Util.fixEmpty(scanCredentialsId);
+  
+    public void setCredentialsId(@CheckForNull String credentialsId) {
+  
+        this.credentialsId = Util.fixEmpty(credentialsId);
    }
+  
+    /**
+  
+     * Gets the repository owner.
+  
+     * @return the repository owner.
+  
+     */
    @NonNull
    public String getRepoOwner() {
        return repoOwner;
    }
+  
+    /**
+  
+     * Gets the repository name.
+  
+     * @return the repository name.
+  
+     */
    @NonNull
    public String getRepository() {
        return repository;
    }
+  
+    /**
+  
+     * {@inheritDoc}
+  
+     * @since 2.2.0
+  
+     */
    @Override
    public List<SCMSourceTrait> getTraits() {
        return traits;
    }
+  
+    /**
+  
+     * Sets the behaviours that are applied to this {@link GitHubSCMSource}.
+  
+     * @param traits the behaviours that are to be applied.
+  
+     */
    @DataBoundSetter
-  
-    public void setTraits(List<SCMSourceTrait> traits) {
-  
-        this.traits = traits == null ? new ArrayList<SCMSourceTrait>() : new ArrayList<SCMSourceTrait>(traits);
+  
+    public void setTraits(@CheckForNull List<SCMSourceTrait> traits) {
+  
+        this.traits = new ArrayList<>(Util.fixNull(traits));
    }
-  
-    /** Use defaults for old settings. */
+  
+    /**
+  
+     * Use defaults for old settings.
+  
+     */
    @SuppressWarnings("ConstantConditions")
    @SuppressFBWarnings(value="RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE", justification="Only non-null after we set them here!")
    private Object readResolve() {
@@ -369,7 +486,9 @@ public String getRemote() {
                .getRepositoryUri(apiUri, repoOwner, repository);
    }
-  
-    /** {@inheritDoc} */
+  
+    /**
+  
+     * {@inheritDoc}
+  
+     */
    @Override
    public String getPronoun() {
        return Messages.GitHubSCMSource_Pronoun();
@@ -1679,6 +1798,10 @@ public LazyContributorNames(GitHubSCMSourceRequest request,
            this.credentials = credentials;
        }
+  
+        /**
+  
+         * {@inheritDoc}
+  
+         */
+  
+        @NonNull
        @Override
        protected Set<String> create() {
            try {
@@ -1699,6 +1822,10 @@ public DeferredContributorNames(GitHubSCMSourceRequest request, TaskListener lis
            this.listener = listener;
        }
+  
+        /**
+  
+         * {@inheritDoc}
+  
+         */
+  
+        @NonNull
        @Override
        protected Set<String> create() {
            if (collaboratorNames != null) {