[JENKINS-43507] Documentation and formatting

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

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) {

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);
     }

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) {