Add documents.

jenkinsci · Dec 22, 2020 · 8e87b22 · 8e87b22
1 parent 0ba4e00
commit 8e87b22
Show file tree

Hide file tree

Showing 2 changed files with 74 additions and 6 deletions.
diff --git a/src/test/java/io/jenkins/plugins/checks/status/BuildStatusChecksPublisherITest.java b/src/test/java/io/jenkins/plugins/checks/status/BuildStatusChecksPublisherITest.java
@@ -13,6 +13,10 @@
 
 import static org.assertj.core.api.Assertions.assertThat;
 
+/**
+ * Tests that the {@link BuildStatusChecksPublisher} listens to the status of a {@link Run} and publishes status
+ * accordingly.
+ */
 public class BuildStatusChecksPublisherITest extends IntegrationTestWithJenkinsPerTest {
     private static final String STATUS_TEMPLATE = "Published Checks (name: %s, status: %s, conclusion %s)%n";
 
@@ -22,9 +26,18 @@ public class BuildStatusChecksPublisherITest extends IntegrationTestWithJenkinsP
     @TestExtension
     public static final LoggingChecksPublisher.Factory PUBLISHER_FACTORY = new LoggingChecksPublisher.Factory();
 
+    /**
+     * Provide inject an implementation of {@link AbstractStatusChecksProperties} to control the checks.
+     */
     @TestExtension
     public static final ChecksProperties PROPERTIES = new ChecksProperties();
 
+    /**
+     * Tests when the implementation of {@link AbstractStatusChecksProperties} is not applicable,
+     * a status checks should not be published.
+     *
+     * @throws IOException if failed getting log from {@link Run}
+     */
     @Test
     public void shouldNotPublishStatusWhenNotApplicable() throws IOException {
         PUBLISHER_FACTORY.setFormatter(details -> String.format(STATUS_TEMPLATE,
@@ -37,6 +50,11 @@ public void shouldNotPublishStatusWhenNotApplicable() throws IOException {
                 .doesNotContain(String.format(STATUS_TEMPLATE, "Test Status", "COMPLETED", "SUCCESS"));
     }
 
+    /**
+     * Tests when status checks is skipped, a status checks should not be published.
+     *
+     * @throws IOException if failed getting log from {@link Run}
+     */
     @Test
     public void shouldNotPublishStatusWhenSkipped() throws IOException {
         PUBLISHER_FACTORY.setFormatter(details -> String.format(STATUS_TEMPLATE,
@@ -49,9 +67,14 @@ public void shouldNotPublishStatusWhenSkipped() throws IOException {
         assertThat(JenkinsRule.getLog(buildSuccessfully(createFreeStyleProject())))
                 .doesNotContain(String.format(STATUS_TEMPLATE, "Test Status", "IN_PROGRESS", "NONE"))
                 .doesNotContain(String.format(STATUS_TEMPLATE, "Test Status", "COMPLETED", "SUCCESS"));
-
     }
 
+    /**
+     * Tests when an implementation of {@link AbstractStatusChecksProperties} is applicable and not skipped,
+     * a status checks using the specified name should be published.
+     *
+     * @throws IOException if failed getting log from {@link Run}
+     */
     @Test
     public void shouldPublishStatusWithProperties() throws IOException {
         PUBLISHER_FACTORY.setFormatter(details -> String.format(STATUS_TEMPLATE,

diff --git a/src/test/java/io/jenkins/plugins/checks/util/LoggingChecksPublisher.java b/src/test/java/io/jenkins/plugins/checks/util/LoggingChecksPublisher.java
@@ -9,20 +9,50 @@
 
 import java.util.Optional;
 
+/**
+ * Implementation of {@link ChecksPublisher} for use in testing, that logs the checks details in user specified format.
+ *
+ * For example:
+ *
+ * <pre>
+ * public class ChecksPublishingTest extends IntegrationTestWithJenkinsPerTest {
+ *
+ *     &#64;TestExtension
+ *     public static final LoggingChecksPublisher.Factory PUBLISHER_FACTORY = new LoggingChecksPublisher.Factory();
+ *
+ *     &#64;Test
+ *     public void shouldLogChecks() {
+ *         // ...Run a test job...
+ *         Run<?, ?> run = buildSuccessfully(createFreeStyleProject());
+ *
+ *         // ...Inspect logs...
+ *         assertThat(JenkinsRule.getLog(run))
+ *                 .contains("...")
+ *                 .doesNotContain("...");
+ *     }
+ * }
+ * </pre>
+ *
+ * An example of this can be found in {@link io.jenkins.plugins.checks.status.BuildStatusChecksPublisherITest}
+ */
 public class LoggingChecksPublisher extends ChecksPublisher {
-    @FunctionalInterface
-    public interface Formatter {
-        String format(ChecksDetails details);
-    }
-
     private Formatter formatter = ChecksDetails::toString;
     private TaskListener listener = TaskListener.NULL;
 
+    /**
+     * Logs the {@code details} using the {@link TaskListener}.
+     *
+     * @param details
+     *         checks details that will be logged
+     */
     @Override
     public void publish(final ChecksDetails details) {
         listener.getLogger().print(formatter.format(details));
     }
 
+    /**
+     * Implementation of {@link ChecksPublisherFactory} that returns a {@link LoggingChecksPublisher}.
+     */
     public static class Factory extends ChecksPublisherFactory {
         private final LoggingChecksPublisher publisher = new LoggingChecksPublisher();
 
@@ -42,4 +72,19 @@ protected Optional<ChecksPublisher> createPublisher(final Job<?, ?> job, final T
             return Optional.of(publisher);
         }
     }
+
+    /**
+     * Defines how to format a {@link ChecksDetails} to {@link String}.
+     */
+    @FunctionalInterface
+    public interface Formatter {
+        /**
+         * Formats the {@code details}.
+         *
+         * @param details
+         *         details to format.
+         * @return formatted string
+         */
+        String format(ChecksDetails details);
+    }
 }