Some more checkstyle (#2297)

* Some more checkstyle

- MissingJavadocMethod

Leniency for test files, helpful suggestions and gradle extension classes.

config/checkstyle/checkstyle-suppressions.xml

@@ -14,13 +14,19 @@
 
   <!-- temporary suppressions as we work through them -->
   <suppress files=".*\.java" checks="VariableDeclarationUsageDistance"/>
-  <suppress files=".*\.java" checks="MissingJavadocMethod"/>
 
   <!-- leniency for json templates -->
   <suppress files=".*[\\/]jib-core[\\/].*Template\.java" checks="MemberName"/>
 
+  <!-- leniency for gradle extension configuration objects -->
+  <suppress files=".*[\\/]jib-gradle-plugin[\\/].*Parameters\.java" checks="MissingJavadocMethod"/>
+
+  <!-- leniency for helpful suggestions -->
+  <suppress files=".*[\\/]HelpfulSuggestions\.java" checks="MissingJavadocMethod"/>
+
   <!-- leniency for test files -->
-  <suppress files=".*[\\/]integration-test[\\/].*\.java" checks="MissingJavadocMethod"/>
-  <suppress files=".*[\\/]integration-test[\\/].*\.java" checks="VariableDeclarationUsageDistance"/>
+  <suppress files=".*[\\/]src[\\/]test[\\/].*\.java" checks="MissingJavadocMethod"/>
+  <suppress files=".*[\\/]src[\\/]integration-test[\\/].*\.java" checks="MissingJavadocMethod"/>
+  <suppress files=".*[\\/]src[\\/]integration-test[\\/].*\.java" checks="VariableDeclarationUsageDistance"/>
 
 </suppressions>

jib-core/src/main/java/com/google/cloud/tools/jib/api/InsecureRegistryException.java

@@ -23,6 +23,12 @@
  */
 public class InsecureRegistryException extends RegistryException {
 
+  /**
+   * Creates a new exception with a human readable message.
+   *
+   * @param insecureUrl the insecure url that is attempted to be accessed
+   * @param cause the underlying cause that triggered this exception
+   */
   public InsecureRegistryException(URL insecureUrl, Throwable cause) {
     super(
         "Failed to verify the server at "

jib-core/src/main/java/com/google/cloud/tools/jib/api/RegistryAuthenticationFailedException.java

@@ -25,13 +25,27 @@ public class RegistryAuthenticationFailedException extends RegistryException {
   private final String serverUrl;
   private final String imageName;
 
+  /**
+   * Creates a new exception with a human readable message.
+   *
+   * @param serverUrl the registry server url
+   * @param imageName the image name that requires authentication
+   * @param cause the underlying cause that triggered this exception
+   */
   public RegistryAuthenticationFailedException(
       String serverUrl, String imageName, Throwable cause) {
     super(MessageFormat.format(REASON, serverUrl, imageName, cause.getMessage()), cause);
     this.serverUrl = serverUrl;
     this.imageName = imageName;
   }
 
+  /**
+   * Creates a new exception with a human readable message.
+   *
+   * @param serverUrl the registry server url
+   * @param imageName the image name that requires authentication
+   * @param reason the underlying reason that triggered this exception
+   */
   public RegistryAuthenticationFailedException(String serverUrl, String imageName, String reason) {
     super(MessageFormat.format(REASON, serverUrl, imageName, reason));
     this.serverUrl = serverUrl;

jib-core/src/main/java/com/google/cloud/tools/jib/builder/steps/StepsRunner.java

@@ -119,6 +119,12 @@ private StepsRunner(ListeningExecutorService executorService, BuildContext build
     this.buildContext = buildContext;
   }
 
+  /**
+   * Add steps for loading an image to docker daemon.
+   *
+   * @param dockerClient the docker client to load the image to
+   * @return this StepsRunner instance
+   */
   public StepsRunner dockerLoadSteps(DockerClient dockerClient) {
     rootProgressDescription = "building image to Docker daemon";
 
@@ -131,6 +137,12 @@ public StepsRunner dockerLoadSteps(DockerClient dockerClient) {
     return this;
   }
 
+  /**
+   * Add steps for writing an image as a tar file archive.
+   *
+   * @param outputPath the target file path to write the image to
+   * @return this StepsRunner instance
+   */
   public StepsRunner tarBuildSteps(Path outputPath) {
     rootProgressDescription = "building image to tar file";
 
@@ -143,6 +155,12 @@ public StepsRunner tarBuildSteps(Path outputPath) {
     return this;
   }
 
+  /**
+   * Add steps for pushing an image to a remote registry. The registry is determined by the image
+   * name.
+   *
+   * @return this StepsRunner instance.
+   */
   public StepsRunner registryPushSteps() {
     rootProgressDescription = "building image to registry";
     boolean layersRequiredLocally = buildContext.getAlwaysCacheBaseImage();
@@ -161,6 +179,13 @@ public StepsRunner registryPushSteps() {
     return this;
   }
 
+  /**
+   * Run all steps and return a BuildResult after a build is completed.
+   *
+   * @return a {@link BuildResult} with build metadata
+   * @throws ExecutionException if an error occured during asynchronous execution of steps
+   * @throws InterruptedException if the build was interrupted while waiting for results
+   */
   public BuildResult run() throws ExecutionException, InterruptedException {
     Preconditions.checkNotNull(rootProgressDescription);
 

jib-core/src/main/java/com/google/cloud/tools/jib/cache/CachedLayer.java

@@ -23,7 +23,7 @@
 import com.google.common.base.Preconditions;
 import javax.annotation.Nullable;
 
-/** Default implementation of {@link CachedLayer}. */
+/** A reference to an image layer that is in the Cache. */
 public class CachedLayer implements Layer {
 
   /** Builds a {@link CachedLayer}. */
@@ -60,6 +60,11 @@ boolean hasLayerBlob() {
       return layerBlob != null;
     }
 
+    /**
+     * Creates a CachedLayer instance.
+     *
+     * @return a new cached layer
+     */
     public CachedLayer build() {
       return new CachedLayer(
           Preconditions.checkNotNull(layerDigest, "layerDigest required"),

jib-core/src/main/java/com/google/cloud/tools/jib/cache/Retry.java

@@ -69,6 +69,12 @@ private Retry(Action<E> action) {
     this.action = action;
   }
 
+  /**
+   * Configure the maximum number of retries.
+   *
+   * @param maximumRetries the number of retries, must be zero or more
+   * @return this Retry instance
+   */
   public Retry<E> maximumRetries(int maximumRetries) {
     Preconditions.checkArgument(maximumRetries > 0);
     this.maximumRetries = maximumRetries;

jib-core/src/main/java/com/google/cloud/tools/jib/configuration/BuildContext.java

@@ -393,6 +393,11 @@ public ImageConfiguration getTargetImageConfiguration() {
     return targetImageConfiguration;
   }
 
+  /**
+   * Returns all image tags configured for this build.
+   *
+   * @return the set of image tags configured for this build
+   */
   public ImmutableSet<String> getAllTargetImageTags() {
     ImmutableSet.Builder<String> allTargetImageTags =
         ImmutableSet.builderWithExpectedSize(1 + additionalTargetImageTags.size());

jib-core/src/main/java/com/google/cloud/tools/jib/configuration/ContainerConfiguration.java

@@ -101,6 +101,12 @@ public Builder setEnvironment(@Nullable Map<String, String> environmentMap) {
       return this;
     }
 
+    /**
+     * Adds an environment entry to the container configuration.
+     *
+     * @param name the environment variable key
+     * @param value the non-null value to associate with environment variable
+     */
     public void addEnvironment(String name, String value) {
       if (environmentMap == null) {
         environmentMap = new HashMap<>();
@@ -125,6 +131,11 @@ public Builder setExposedPorts(@Nullable Set<Port> exposedPorts) {
       return this;
     }
 
+    /**
+     * Adds an exposed port entry to the container configuration.
+     *
+     * @param port the non-null port to add
+     */
     public void addExposedPort(Port port) {
       if (exposedPorts == null) {
         exposedPorts = new HashSet<>();
@@ -148,6 +159,11 @@ public Builder setVolumes(@Nullable Set<AbsoluteUnixPath> volumes) {
       return this;
     }
 
+    /**
+     * Adds a volume entry to the container configuration.
+     *
+     * @param volume the absolute path to add as a volume entry
+     */
     public void addVolume(AbsoluteUnixPath volume) {
       if (volumes == null) {
         volumes = new HashSet<>();
@@ -174,6 +190,12 @@ public Builder setLabels(@Nullable Map<String, String> labels) {
       return this;
     }
 
+    /**
+     * Add a label to the container configuration.
+     *
+     * @param key the label name to add
+     * @param value the value to be associated with the label
+     */
     public void addLabel(String key, String value) {
       if (labels == null) {
         labels = new HashMap<>();

jib-core/src/main/java/com/google/cloud/tools/jib/docker/DockerClient.java

@@ -79,6 +79,12 @@ public DescriptorDigest getImageId() throws DigestException {
       return DescriptorDigest.fromDigest(imageId);
     }
 
+    /**
+     * Return a list of diff ids of the layers in the image.
+     *
+     * @return a list of diff ids
+     * @throws DigestException if a digest is invalid
+     */
     public List<DescriptorDigest> getDiffIds() throws DigestException {
       List<DescriptorDigest> processedDiffIds = new ArrayList<>(rootFs.layers.size());
       for (String diffId : rootFs.layers) {

jib-core/src/main/java/com/google/cloud/tools/jib/event/progress/ThrottledAccumulatingConsumer.java

@@ -51,6 +51,13 @@ public ThrottledAccumulatingConsumer(Consumer<Long> callback) {
     this(callback, Duration.ofMillis(100), Instant::now);
   }
 
+  /**
+   * A new configured consumer.
+   *
+   * @param consumer {@link Consumer} callback to wrap
+   * @param delayBetweenCallbacks delay between each call to the underlying accept
+   * @param getNow supplies of the current time {@link Instant}
+   */
   public ThrottledAccumulatingConsumer(
       Consumer<Long> consumer, Duration delayBetweenCallbacks, Supplier<Instant> getNow) {
     this.consumer = consumer;

jib-core/src/main/java/com/google/cloud/tools/jib/frontend/CredentialRetrieverFactory.java

@@ -214,6 +214,14 @@ public CredentialRetriever dockerConfig(Path dockerConfigFile) {
         DockerConfigCredentialRetriever.create(imageReference.getRegistry(), dockerConfigFile));
   }
 
+  /**
+   * Creates a new {@link CredentialRetriever} that tries to retrieve credentials from a legacy
+   * Docker config file.
+   *
+   * @param dockerConfigFile the path to a legacy docker configuration file
+   * @return a new {@link CredentialRetriever}
+   * @see DockerConfigCredentialRetriever
+   */
   public CredentialRetriever legacyDockerConfig(Path dockerConfigFile) {
     return dockerConfig(
         DockerConfigCredentialRetriever.createForLegacyFormat(

jib-core/src/main/java/com/google/cloud/tools/jib/http/BlobHttpContent.java

@@ -33,6 +33,13 @@ public BlobHttpContent(Blob blob, String contentType) {
     this(blob, contentType, ignored -> {});
   }
 
+  /**
+   * Create a new BlobHttpClient.
+   *
+   * @param blob a blob to wrap
+   * @param contentType the http contentType descriptor
+   * @param writtenByteCountListener to listen for written byte feedback
+   */
   public BlobHttpContent(Blob blob, String contentType, Consumer<Long> writtenByteCountListener) {
     this.blob = blob;
     this.contentType = contentType;

jib-core/src/main/java/com/google/cloud/tools/jib/http/FailoverHttpClient.java

@@ -125,6 +125,13 @@ private static HttpTransport getInsecureHttpTransport() {
   private final Deque<HttpTransport> transportsCreated = new ArrayDeque<>();
   private final Deque<Response> responsesCreated = new ArrayDeque<>();
 
+  /**
+   * Create a new FailoverHttpclient.
+   *
+   * @param enableHttpAndInsecureFailover to enable automatic failover to insecure connection types
+   * @param sendAuthorizationOverHttp allow sending auth over http connections
+   * @param logger to receive log events
+   */
   public FailoverHttpClient(
       boolean enableHttpAndInsecureFailover,
       boolean sendAuthorizationOverHttp,

jib-core/src/main/java/com/google/cloud/tools/jib/image/Image.java

@@ -250,6 +250,11 @@ public Builder addHistory(HistoryEntry history) {
       return this;
     }
 
+    /**
+     * Create an {@link Image} instance.
+     *
+     * @return a new {@link Image} instance
+     */
     public Image build() {
       return new Image(
           imageFormat,

jib-core/src/main/java/com/google/cloud/tools/jib/image/ImageTarball.java

@@ -64,6 +64,13 @@ public ImageTarball(
     this.allTargetImageTags = allTargetImageTags;
   }
 
+  /**
+   * Writes image tar bar in configured {@link Image#getImageFormat()} of OCI or Docker to output
+   * stream.
+   *
+   * @param out the target output stream
+   * @throws IOException if an error occurs writing out the image to stream
+   */
   public void writeTo(OutputStream out) throws IOException {
     if (image.getImageFormat() == OciManifestTemplate.class) {
       ociWriteTo(out);

jib-core/src/main/java/com/google/cloud/tools/jib/image/json/ContainerConfigurationTemplate.java

@@ -205,34 +205,59 @@ public void setContainerCmd(@Nullable List<String> cmd) {
     config.Cmd = cmd;
   }
 
+  /**
+   * Sets test on HealthCheck, creates an empty HealthCheck object if necessary.
+   *
+   * @param test the list of tests to set
+   */
   public void setContainerHealthCheckTest(List<String> test) {
     if (config.Healthcheck == null) {
       config.Healthcheck = new HealthCheckObjectTemplate();
     }
     Preconditions.checkNotNull(config.Healthcheck).Test = test;
   }
 
+  /**
+   * Sets interval on HealthCheck, creates an empty HealthCheck object if necessary.
+   *
+   * @param interval the interval to set
+   */
   public void setContainerHealthCheckInterval(@Nullable Long interval) {
     if (config.Healthcheck == null) {
       config.Healthcheck = new HealthCheckObjectTemplate();
     }
     Preconditions.checkNotNull(config.Healthcheck).Interval = interval;
   }
 
+  /**
+   * Sets timeout on HealthCheck, creates an empty HealthCheck object if necessary.
+   *
+   * @param timeout the timeout to configure
+   */
   public void setContainerHealthCheckTimeout(@Nullable Long timeout) {
     if (config.Healthcheck == null) {
       config.Healthcheck = new HealthCheckObjectTemplate();
     }
     Preconditions.checkNotNull(config.Healthcheck).Timeout = timeout;
   }
 
+  /**
+   * Sets startPeriod on HealthCheck, creates an empty HealthCheck object if necessary.
+   *
+   * @param startPeriod the start period to configure
+   */
   public void setContainerHealthCheckStartPeriod(@Nullable Long startPeriod) {
     if (config.Healthcheck == null) {
       config.Healthcheck = new HealthCheckObjectTemplate();
     }
     Preconditions.checkNotNull(config.Healthcheck).StartPeriod = startPeriod;
   }
 
+  /**
+   * Sets retries on HealthCheck, creates an empty HealthCheck object if necessary.
+   *
+   * @param retries the number of retries to configure
+   */
   public void setContainerHealthCheckRetries(@Nullable Integer retries) {
     if (config.Healthcheck == null) {
       config.Healthcheck = new HealthCheckObjectTemplate();

jib-core/src/main/java/com/google/cloud/tools/jib/image/json/HistoryEntry.java

@@ -66,6 +66,11 @@ public Builder setEmptyLayer(Boolean emptyLayer) {
       return this;
     }
 
+    /**
+     * Create a new history entry.
+     *
+     * @return an new {@link HistoryEntry} instance
+     */
     public HistoryEntry build() {
       return new HistoryEntry(
           creationTimestamp == null ? null : creationTimestamp.toString(),

jib-core/src/main/java/com/google/cloud/tools/jib/image/json/V21ManifestTemplate.java

@@ -93,6 +93,11 @@ private static class HistoryObjectTemplate implements JsonTemplate {
     @Nullable private String v1Compatibility;
   }
 
+  /**
+   * Returns a list of descriptor digests for the layers in the image.
+   *
+   * @return a list of descriptor digests for the layers in the image.
+   */
   public List<DescriptorDigest> getLayerDigests() {
     List<DescriptorDigest> layerDigests = new ArrayList<>();