tidy up/add some docs

buildSrc/src/main/kotlin/buildsrc/conventions/publishing.gradle.kts

@@ -84,6 +84,8 @@ signing {
     sign(publishing.publications)
 
     setRequired({
+        // only enable signing for non-snapshot versions, or when publishing to a non-local repo, otherwise
+        // publishing to Maven Local requires signing for users without access to the signing key.
         !isSnapshotVersion() || gradle.taskGraph.hasTask("publish")
     })
 }
@@ -99,6 +101,7 @@ tasks.withType<AbstractPublishToMaven>().configureEach {
 }
 
 val javadocJar by tasks.registering(Jar::class) {
+    description = "Generate Javadoc using Dokka"
     dependsOn(tasks.dokkaJavadoc)
     from(tasks.dokkaJavadoc)
     archiveClassifier.set("javadoc")

buildSrc/src/main/kotlin/buildsrc/conventions/sonarqube.gradle.kts

@@ -17,16 +17,27 @@
 
 package buildsrc.conventions
 
-import buildsrc.utils.Rife2TestListener
-import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-import org.gradle.api.tasks.testing.logging.TestLogEvent
 import org.sonarqube.gradle.SonarTask
 
+/**
+ * Convention plugin for SonarQube analysis.
+ *
+ * SonarQube depends on an aggregated XML coverage report from
+ * [Kotlinx Kover](https://github.com/Kotlin/kotlinx-kover).
+ * See the Kover docs for
+ * [how to aggregate coverage reports](https://kotlin.github.io/kotlinx-kover/gradle-plugin/#multiproject-build).
+ */
+
 plugins {
     id("org.sonarqube")
     id("org.jetbrains.kotlinx.kover")
 }
 
+if (project != rootProject) {
+    logger.warn("The SonarQube convention plugin should only be applied to the root project")
+    // https://docs.sonarqube.org/latest/analyzing-source-code/scanners/sonarscanner-for-gradle/#analyzing-multi-project-builds
+}
+
 sonarqube {
     properties {
         property("sonar.projectName", rootProject.name)
@@ -39,5 +50,6 @@ sonarqube {
 }
 
 tasks.withType<SonarTask>().configureEach {
+    // workaround for https://github.com/Kotlin/kotlinx-kover/issues/394
     dependsOn(tasks.matching { it.name == "koverXmlReport" })
 }