Document several classes

Author: erichaagdev

src/main/java/dev/erichaag/develocity/processing/BuildListener.java

@@ -11,28 +11,92 @@
 
 import static java.util.Collections.emptySet;
 
+/**
+ * A listener interface for receiving notifications about builds encountered
+ * during processing.
+ *
+ * <p>Implement this interface to receive callbacks when builds are encountered
+ * by a {@link BuildProcessor}. A {@link BuildListenerBuilder} provides a
+ * convenient way to create custom listeners without needing to write a
+ * dedicated class that implements this interface.
+ *
+ * <p>Note that it can sometimes be useful for an implementation to also
+ * implement {@link ProcessListener} if it needs to be notified about a specific
+ * processing stage. For example, when all processing has finished so that the
+ * listener can perform a final action.
+ *
+ * <p>By default, all methods have empty implementations. Implement only the
+ * methods relevant to your use case.
+ *
+ * @see BuildListenerBuilder
+ * @see ProcessListener
+ */
 public interface BuildListener {
 
+    /**
+     * Creates a new {@link BuildListenerBuilder} to construct a
+     * {@link BuildListener} instance.
+     *
+     * <p>This can be convenient to quickly construct listeners without needing
+     * to write a dedicated class that implements this interface.
+     *
+     * @return a new builder instance
+     */
     static BuildListenerBuilder builder() {
         return new BuildListenerBuilder();
     }
 
+    /**
+     * Returns the set of {@link BuildModel}s required by this listener.
+     * This information is used by a {@link BuildProcessor} to know which build
+     * models to request.
+     *
+     * <p>By default, this method returns an empty set, indicating that no
+     * additional build models are required by this listener.
+     *
+     * @return the set of required build models
+     */
     default Set<BuildModel> getRequiredBuildModels() {
         return emptySet();
     }
 
+    /**
+     * Callback method invoked when any build is encountered.
+     *
+     * @param build the build that was encountered
+     */
     default void onBuild(Build build) {
     }
 
+    /**
+     * Callback method invoked when a Gradle build is encountered.
+     *
+     * @param build the Gradle build that was encountered
+     */
     default void onGradleBuild(GradleBuild build) {
     }
 
+    /**
+     * Callback method invoked when a Maven build is encountered.
+     *
+     * @param build the Maven build that was encountered
+     */
     default void onMavenBuild(MavenBuild build) {
     }
 
+    /**
+     * Callback method invoked when a Bazel build is encountered.
+     *
+     * @param build the Bazel build that was encountered
+     */
     default void onBazelBuild(BazelBuild build) {
     }
 
+    /**
+     * Callback method invoked when an sbt build is encountered.
+     *
+     * @param build the Sbt build that was encountered
+     */
     default void onSbtBuild(SbtBuild build) {
     }
 

src/main/java/dev/erichaag/develocity/processing/BuildListenerBuilder.java

@@ -15,6 +15,22 @@
 
 import static java.util.Set.copyOf;
 
+/**
+ * A builder class for constructing a {@link BuildListener} instance.
+ *
+ * <p>An instance of this builder can be obtained by calling
+ * {@link BuildListener#builder()}.
+ *
+ * <p>This builder allows you to create a {@link BuildListener} by specifying
+ * the desired callback methods and the required build models. This builder can
+ * be convenient to quickly construct listeners without needing to write a
+ * dedicated class that implements {@link BuildListener}.
+ *
+ * <p>This builder provides a fluent interface, allowing method calls to be
+ * chained together to register multiple callbacks for different builds.
+ *
+ * @see BuildListener
+ */
 public final class BuildListenerBuilder {
 
     private final List<BuildListener> listeners = new ArrayList<>();
@@ -23,6 +39,15 @@ public final class BuildListenerBuilder {
     BuildListenerBuilder() {
     }
 
+    /**
+     * Constructs a new {@link BuildListener} instance with the configured
+     * callbacks and required build models.
+     *
+     * <p>The returned listener will invoke all registered listener methods
+     * when builds are encountered.
+     *
+     * @return a new {@link BuildListener} instance
+     */
     public BuildListener build() {
         return new BuildListener() {
 
@@ -59,11 +84,28 @@ public void onSbtBuild(SbtBuild build) {
         };
     }
 
+    /**
+     * Adds the specified build models required by the constructed
+     * {@link BuildListener}. This information is used by a
+     * {@link BuildProcessor} to know which build models to request.
+     *
+     * <p>Calling this method more than once will add the supplied build models
+     * to the set of required build models. Duplicate build models are ignored.
+     *
+     * @param buildModels the build models required by the constructed listener
+     * @return this builder instance for fluent configuration
+     */
     public BuildListenerBuilder requiredBuildModels(BuildModel... buildModels) {
         requiredBuildModels.addAll(Set.of(buildModels));
         return this;
     }
 
+    /**
+     * Registers a callback function to be invoked when any build is encountered.
+     *
+     * @param onBuild the callback function to execute
+     * @return this builder instance for fluent configuration
+     */
     public BuildListenerBuilder onBuild(Consumer<Build> onBuild) {
         listeners.add(new BuildListener() {
             @Override
@@ -74,6 +116,13 @@ public void onBuild(Build build) {
         return this;
     }
 
+    /**
+     * Registers a callback function to be invoked when a Gradle build is
+     * encountered.
+     *
+     * @param onGradleBuild the callback function to execute
+     * @return this builder instance for fluent configuration
+     */
     public BuildListenerBuilder onGradleBuild(Consumer<GradleBuild> onGradleBuild) {
         listeners.add(new BuildListener() {
             @Override
@@ -84,6 +133,13 @@ public void onGradleBuild(GradleBuild build) {
         return this;
     }
 
+    /**
+     * Registers a callback function to be invoked when a Maven build is
+     * encountered.
+     *
+     * @param onMavenBuild the callback function to execute
+     * @return this builder instance for fluent configuration
+     */
     public BuildListenerBuilder onMavenBuild(Consumer<MavenBuild> onMavenBuild) {
         listeners.add(new BuildListener() {
             @Override
@@ -94,6 +150,13 @@ public void onMavenBuild(MavenBuild build) {
         return this;
     }
 
+    /**
+     * Registers a callback function to be invoked when a Bazel build is
+     * encountered.
+     *
+     * @param onBazelBuild the callback function to execute
+     * @return this builder instance for fluent configuration
+     */
     public BuildListenerBuilder onBazelBuild(Consumer<BazelBuild> onBazelBuild) {
         listeners.add(new BuildListener() {
             @Override
@@ -104,6 +167,13 @@ public void onBazelBuild(BazelBuild build) {
         return this;
     }
 
+    /**
+     * Registers a callback function to be invoked when an sbt build is
+     * encountered.
+     *
+     * @param onSbtBuild the callback function to execute
+     * @return this builder instance for fluent configuration
+     */
     public BuildListenerBuilder onSbtBuild(Consumer<SbtBuild> onSbtBuild) {
         listeners.add(new BuildListener() {
             @Override

src/main/java/dev/erichaag/develocity/processing/BuildProcessor.java

@@ -20,7 +20,6 @@
 import static java.util.Objects.requireNonNullElseGet;
 import static java.util.Optional.empty;
 import static java.util.stream.Collectors.toUnmodifiableSet;
-import static java.util.stream.Stream.concat;
 
 public final class BuildProcessor {
 
@@ -46,8 +45,7 @@ public final class BuildProcessor {
             Integer retryLimit,
             Double retryFactor,
             List<BuildListener> buildListeners,
-            List<ProcessListener> processListeners,
-            Set<BuildModel> requiredBuildModels
+            List<ProcessListener> processListeners
     ) {
         this.develocity = develocity;
         this.processorCache = requireNonNullElseGet(processorCache, NoopCache::new);
@@ -58,7 +56,8 @@ public final class BuildProcessor {
         this.retryFactor = requireNonNullElse(retryFactor, 1.5);
         this.buildListeners = buildListeners;
         this.processListeners = processListeners;
-        this.requiredBuildModels = concat(requiredBuildModels.stream(), buildListeners.stream().flatMap(it -> it.getRequiredBuildModels().stream()))
+        this.requiredBuildModels = buildListeners.stream()
+                .flatMap(it -> it.getRequiredBuildModels().stream())
                 .collect(toUnmodifiableSet());
         validate();
     }