Merge pull request #537 from jeetchoudhary/master

updating source code per java-doc standards

Author: afalko

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/model/FromInstruction.java

@@ -92,12 +92,13 @@ private FromInstruction(String baseImageName, String tag, List<String> additiona
     }
 
     /**
-     * Check if this {@code lineInFile} is a FROM instruction, it is referencing {@code imageName} as a base image,
-     * and the tag is not the same as {@code imageTag} (or there is no tag)
-     *
-     * @param lineInFile a single line from a file
-     * @param imageName the base image name we're looking for
-     * @param imageTag the proposed new tag
+     *  Check if this {@code lineInFile} is a FROM instruction,
+     *  it is referencing {@code imageName} as a base image,
+     *  and the tag is not the same as {@code imageTag} (or there is no tag)
+     * @param lineInFile Line a code file
+     * @param imageName images name
+     * @param imageTag tag for imageName
+     * @return {@link Boolean} value isFromInstructionWithThisImageAndOlderTag
      */
     public static boolean isFromInstructionWithThisImageAndOlderTag(String lineInFile, String imageName, String imageTag) {
         if (FromInstruction.isFromInstruction(lineInFile)) {

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/model/ShouldForkResult.java

@@ -25,11 +25,12 @@ public static ShouldForkResult shouldNotForkResult(String reason) {
         return new ShouldForkResult(false, reason);
     }
 
+
     /**
-     * Allows for chaining ShouldForkResult instances such that and() will return the first
-     * ShouldForkResult which results in isForkable() == false.
-     *
+     * Allows for chaining ShouldForkResult instances such that and() will
+     * return the first ShouldForkResult which results in isForkable() == false.
      * @param otherShouldForkResult the other ShouldForkResult to return if this is forkable.
+     * @return chainable {@code ShouldForkResult}
      */
     public ShouldForkResult and(ShouldForkResult otherShouldForkResult) {
         if (isForkable()) {

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/process/ForkableRepoValidator.java

@@ -41,6 +41,7 @@ public ForkableRepoValidator(DockerfileGitHubUtil dockerfileGitHubUtil) {
      *
      * @param parentRepo parent repo we're checking
      * @param searchResultContent search result content we'll check against
+     * @param gitForkBranch forked git branch
      * @return should we fork the parentRepo?
      */
     public ShouldForkResult shouldFork(GHRepository parentRepo,
@@ -57,7 +58,8 @@ public ShouldForkResult shouldFork(GHRepository parentRepo,
      * whether that content has a qualifying base image update
      * @param parentRepo parentRepo which we'd fork off of
      * @param searchResultContent search result with path to check in parent repo's default branch (where we'd PR)
-     * @param gitForkBranch information about the imageName we'd like to update with the new tag
+     * @param gitForkBranch information about the imageName we'd like to update with the new tag.
+     * @return {@code ShouldForkResult } Object
      */
     protected ShouldForkResult contentHasChangesInDefaultBranch(GHRepository parentRepo,
                                                                 GHContent searchResultContent,
@@ -90,6 +92,7 @@ protected ShouldForkResult contentHasChangesInDefaultBranch(GHRepository parentR
      *
      * @param content content to check
      * @param gitForkBranch information about the base image we'd like to update
+     * @return {@code Boolean} value signifying whether there are any changes content
      */
     protected boolean hasNoChanges(GHContent content, GitForkBranch gitForkBranch) {
         try (InputStream stream = content.read();
@@ -115,6 +118,7 @@ protected boolean hasNoChanges(GHContent content, GitForkBranch gitForkBranch) {
      * If this user is the owner of the repo, do not fork.
      *
      * @param parentRepo parent repo we're checking
+     * @return {@code ShouldForkResult} Object abstracting data if the user is owner of the repo
      */
     protected ShouldForkResult thisUserIsNotOwner(GHRepository parentRepo) {
         try {
@@ -131,6 +135,7 @@ protected ShouldForkResult thisUserIsNotOwner(GHRepository parentRepo) {
      * Check if parentRepo is a fork. Do not fork a fork (for now, at least).
      *
      * @param parentRepo parent repo we're checking
+     * @return {@code ShouldForkResult} Object abstracting data if parentRepo is a fork
      */
     protected ShouldForkResult parentIsFork(GHRepository parentRepo) {
         return parentRepo.isFork() ? shouldNotForkResult(REPO_IS_FORK) : shouldForkResult();
@@ -140,6 +145,7 @@ protected ShouldForkResult parentIsFork(GHRepository parentRepo) {
      * Check if parentRepo is archived. We won't be able to update it, so do not fork.
      *
      * @param parentRepo parent repo we're checking
+     * @return {@code ShouldForkResult} Object abstracting data if parentRepo is archived
      */
     protected ShouldForkResult parentIsArchived(GHRepository parentRepo) {
         return parentRepo.isArchived() ? shouldNotForkResult(REPO_IS_ARCHIVED) : shouldForkResult();

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/process/GitHubPullRequestSender.java

@@ -114,6 +114,7 @@ private void ensureForkedAndAddToListForProcessing(Multimap<String, GitHubConten
      *
      * @param pathToDockerfilesInParentRepo processing multimap
      * @param parentRepoName name of parent repo to find
+     * @return {@code GHRepository} return the fork from existing record
      */
     protected GHRepository getForkFromExistingRecordToProcess(Multimap<String, GitHubContentToProcess> pathToDockerfilesInParentRepo,
                                                             String parentRepoName) {

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/storage/GitHubJsonStore.java

@@ -59,12 +59,12 @@ public void updateStore(String img, String tag) throws IOException {
     }
 
     /**
-     * This methods will check if the tag store at {@param path}
+     * This methods will check if the tag store at path
      * is created or not, if not it will create a new tag store.
      *
      * @param repo {@link GHRepository} git repository object.
      * @param path filename with path with in repo for the tag store.
-     * @throws IOException when tag store at {@param path}
+     * @throws IOException when tag store at path
      *                     can not be created.
      */
     public void initializeTagStoreIfRequired(GHRepository repo, String path) throws IOException {

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/storage/ImageTagStore.java

@@ -16,6 +16,7 @@ public interface ImageTagStore {
      *
      * @param img the name of the image that needs to be updated.
      * @param tag the version of the image that it needs to update to.
+     * @throws IOException when fails to update tag store
      */
     void updateStore(String img, String tag) throws IOException;
 
@@ -25,6 +26,9 @@ public interface ImageTagStore {
      * @param dockerfileGitHubUtil the dockerfileGitHubUtil object that is used to interact with an underlying Git repo.
      * @param storeName the name of the store whose content needs to be fetched.
      * @return A Map of image name to image version.
+     * @throws IOException when fails to get the tag store content
+     * @throws InterruptedException when interrupted while getting the tag store content
      */
+
     List<ImageTagStoreContent> getStoreContent(DockerfileGitHubUtil dockerfileGitHubUtil, String storeName) throws IOException, InterruptedException;
 }

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/storage/S3BackedImageTagStore.java

@@ -51,7 +51,7 @@ public void updateStore(String img, String tag) throws IOException {
     /**
      * This method gets the content of the image tag store backed by S3.
      *
-     * @param dockerfileGitHubUtil
+     * @param dockerfileGitHubUtil {@code DockerfileGitHubUtil} Object
      * @param storeName The name of the store.
      * @return List of ImageTagStoreContent objects that contain the image name and the image tag.
      */

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/utils/DockerfileGitHubUtil.java

@@ -398,6 +398,8 @@ public Optional<GHPullRequest> getPullRequestForImageBranch(GHRepository reposit
      * @param parent parent repo to base from
      * @param fork fork repo where we'll create or modify the {@code gitForkBranch}
      * @param gitForkBranch desired branch to create or update based on the parent's default branch
+     * @throws IOException if there is any failure while I/O.
+     * @throws InterruptedException if interrupted during updating forked branch
      */
     public void createOrUpdateForkBranchToParentDefault(GHRepository parent, GHRepository fork, GitForkBranch gitForkBranch) throws IOException, InterruptedException {
         GHBranch parentBranch = parent.getBranch(parent.getDefaultBranch());
@@ -433,6 +435,10 @@ public boolean thisUserIsOwner(GHRepository repo) throws IOException {
      *
      * @param org GitHub organization
      * @param img image to find
+     * @param gitApiSearchLimit git api search limit
+     * @throws IOException if there is any failure while I/O from git.
+     * @throws InterruptedException if interrupted while fetching git content
+     * @return {@code Optional} of {@code PagedSearchIterable}
      */
     public Optional<List<PagedSearchIterable<GHContent>>> getGHContents(String org, String img, Integer gitApiSearchLimit)
             throws IOException, InterruptedException {

dockerfile-image-update/src/main/java/com/salesforce/dockerfileimageupdate/utils/GitHubUtil.java

@@ -83,6 +83,7 @@ public GHRepository createFork(GHRepository repo) {
     /**
      * Attempt to delete the GitHub repo if there are no pull requests associated with it
      * @param repo the repo to delete
+     * @throws IOException if fails to delete repo.
      */
     public void safeDeleteRepo(GHRepository repo) throws IOException {
         if (!repo.queryPullRequests().state(GHIssueState.OPEN).list().iterator().hasNext()) {
@@ -142,6 +143,8 @@ public int createPullReq(GHRepository origRepo, String branch,
      *
      * @param repo - wait until we can retrieve {@code branch from this repo}
      * @param branchName - the branch to wait for
+     * @return {@code GHBranch} Object for the branchName
+     * @throws InterruptedException if interrupted while retrieving the branch
      */
     protected GHBranch tryRetrievingBranch(GHRepository repo, String branchName) throws InterruptedException {
         for (int i = 0; i < 10; i++) {