additional readme docs

Author: aSemy

README.md

@@ -6,6 +6,11 @@ BCV-MU is a re-imagined [Gradle](https://gradle.org/) Plugin for
 This plugin validates the public JVM binary API of libraries to make sure that breaking changes are
 tracked.
 
+Read more in the BCV project:
+
+* [What constitutes the public API?](https://github.com/Kotlin/binary-compatibility-validator/#what-constitutes-the-public-api)
+* [What makes an incompatible change to the public binary API?](https://github.com/Kotlin/binary-compatibility-validator/#what-makes-an-incompatible-change-to-the-public-binary-api)
+
 (The [Mirror Universe](https://en.wikipedia.org/wiki/Mirror_Universe) tag was chosen because I hope
 to banish this plugin as soon the improvements here are merged upstream.)
 
@@ -14,8 +19,6 @@ to banish this plugin as soon the improvements here are merged upstream.)
 Under-the-hood BCV-MU still uses the signature-generation code from BCV, but the Gradle plugin has
 been refactored to better follow the Gradle API, and generate API signatures more flexibly.
 
-### Quick start
-
 BCV-MU plugin can either be [applied as to a Project](#build-plugin) in any `build.gradle(.kts)`,
 or (**experimentally**) [as a Settings plugin](#settings-plugin) in `settings.gradle(.kts)`.
 
@@ -26,15 +29,96 @@ The minimal supported Gradle version is 7.6.
 By default, BCV-MU uses BCV version `0.13.0`, which can be overridden, but may introduce runtime
 errors.
 
-#### Build plugin
+### Build plugin
+
+BCV-MU can be applied to each subproject as a standard Gradle plugin.
+
+```kotlin
+// build.gradle.kts
+
+plugins {
+  id("dev.adamko.kotlin.binary-compatibility-validator") version "$bcvMuVersion"
+}
+```
+
+To initialise the API declarations, run the Gradle task
+
+```shell
+./gradlew apiDump
+```
+
+This will produce API files into the `./api` directory of subprojects with the BCV-MU plugin.
+These API declarations files must be committed to the repository.
+
+To verify that the API declarations is up-to-date, run the Gradle task
+
+```shell
+./gradlew apiCheck
+```
+
+The `apiCheck` task will also be run whenever the `check` task is run.
+
+##### Configuration
+
+BCV-MU can be configured in a similar manner to BCV:
 
-BCV-MU can be applied to each subproject.
+```kotlin
+// build.gradle.kts
+
+plugins {
+  kotlin("jvm") version "1.8.10"
+  id("dev.adamko.kotlin.binary-compatibility-validator") version "$bcvMuVersion"
+}
+
+binaryCompatibilityValidator {
+  // Packages that are excluded from public API dumps even if they contain public API.
+  ignoredPackages.add("kotlinx.coroutines.internal")
+  // Classes (fully qualified) that are excluded from public API dumps even if they contain public API.
+  ignoredClasses.add("com.company.BuildConfig")
+  // Set of annotations that exclude API from being public.
+  // Typically, it is all kinds of `@InternalApi` annotations that mark
+  // effectively private API that cannot be actually private for technical reasons.
+  ignoredMarkers.add("my.package.MyInternalApiAnnotation")
+
+  // Disable or enable all BCV-MU tasks for this project
+  bcvEnabled.set(true)
+
+  // Override the default BCV version
+  kotlinxBinaryCompatibilityValidatorVersion.set("0.13.0")
+}
+```
+
+##### Advanced configuration
+
+BCV automatically generates 'targets' for each Kotlin/JVM target that it finds.
+These targets can be specifically modified, or manually defined, for fine-grained control.
 
 ```kotlin
 // build.gradle.kts
 
 plugins {
+  kotlin("jvm") version "1.8.10"
   id("dev.adamko.kotlin.binary-compatibility-validator") version "$bcvMuVersion"
+  `java-test-fixtures`
+}
+
+binaryCompatibilityValidator {
+  // these are the default values that will be used in all Targets
+  ignoredMarkers.add("my.package.MyFirstInternalApiAnnotation")
+  ignoredClasses.add("com.company.BuildConfig")
+
+  // BCV will automatically generate targets for each Kotlin/JVM target,
+  // and each can be configured manually for fine-grained control. 
+  targets.configureEach {
+    // values can be appended to the default values
+    ignoredMarkers.add("my.package.MySecondInternalApiAnnotation")
+    // Or overridden
+    ignoredClasses.set(listOf())
+  }
+  // BCV Targets can also be manually defined
+  targets.register("testFixtures") {
+    inputJar.set(tasks.testFixturesJar)
+  }
 }
 ```
 

build.gradle.kts

@@ -31,6 +31,9 @@ val readmeCheck by tasks.registering {
       require("BCV version `${kotlinBcvVersion.get()}`" in readme) {
         "Incorrect BCV version in README"
       }
+      require("kotlinxBinaryCompatibilityValidatorVersion.set(\"${kotlinBcvVersion.get()}\")" in readme) {
+        "Incorrect BCV version in README"
+      }
       require("The minimal supported Gradle version is ${minimumGradleTestVersion.get()}" in readme) {
         "Incorrect Gradle version in README"
       }

modules/bcv-gradle-plugin/src/main/kotlin/BCVProjectPlugin.kt

@@ -169,5 +169,4 @@ abstract class BCVProjectPlugin @Inject constructor(
       }
     }
   }
-
 }