more work on JavaDoc

skippy-gradle/src/main/java/io/skippy/gradle/SkippyPlugin.java

@@ -19,18 +19,52 @@
 import io.skippy.gradle.collector.ClassFileCollector;
 import io.skippy.gradle.collector.SkippifiedTestCollector;
 import io.skippy.gradle.coveragebuild.CoverageBuild;
+import io.skippy.gradle.model.SkippifiedTest;
 import org.gradle.api.Project;
 import org.gradle.api.plugins.JavaPlugin;
 import org.gradle.api.tasks.SourceSetContainer;
 
 /**
- * Adds Skippy support for Gradle:
+ * Adds Skippy support for Gradle.
+ * <br />
+ * <br />
+ * In order to understand how the plugin works, it's crucial to distinguish between two types of builds:
  * <ul>
- *     <li>Add the {@code skippyClean} and {@code skippyAnalyze} tasks if the build has been triggered "normally".</li>
- *     <li>If the build was triggered by the {@link AnalyzeTask} to capture coverage data for a skippified test,
- *     the plugin performs the necessary configuration changes.</li>
+ *      <li>Regular builds </li>
+ *      <li>Coverage builds for skippified tests</li>
  * </ul>
  *
+ * Regular build are started by the user directly (e.g., by invoking {@code ./gradlew skippyAnalyze} on the command line).
+ * Coverage builds for skippified tests are started by the {@link AnalyzeTask} for each {@link SkippifiedTest} in the
+ * project. Coverage builds are started internally.
+ *
+ * <br />
+ * <br />
+ * Consider the following example:
+ *
+ * <pre>
+ * // regular build
+ * ./gradlew skippyAnalyze
+ *   │
+ *   │  // coverage build
+ *   ├─ ./gradlew test jacocoTestReport -PskippyCoverageBuild=true -PskippyClassFile=[..]/FooTest.class ...
+ *   │
+ *   │  // coverage build
+ *   └─ ./gradlew test jacocoTestReport -PskippyCoverageBuild=true -PskippyClassFile=[..]/BarTest.class ...
+ * </pre>
+ *
+ * {@code ./gradlew skippyAnalyze} starts a regular build. Under the hood, {@code skippyAnalyze}
+ * starts coverage builds to capture coverage information for tests {@code FooTest} and {@code BarTest}.
+ *
+ * <br />
+ * <br />
+ *
+ * The Skippy Plugin distinguishes between two cases:
+ * <ol>
+ *     <li>Regular build: Adds the {@code skippyClean} and {@code skippyAnalyze} tasks</li>
+ *     <li>Coverage builds: Apply necessary configuration changes (e.g., update the test task to only run a single test)</li>
+ * </ol>
+ *
  * @author Florian McKee
  */
 public final class SkippyPlugin implements org.gradle.api.Plugin<Project> {