build: Set up JD cross-linking between submodules

build-logic/src/main/kotlin/CopyJavadoc.kt

@@ -13,7 +13,7 @@ import org.gradle.api.tasks.options.Option
 import java.io.File
 import javax.inject.Inject
 
-private const val ADVENTURE_PREFIX = "adventure-"
+internal const val ADVENTURE_PREFIX = "adventure-"
 
 /**
  * Copy project javadoc into the `adventure-javadoc` directory tree
@@ -43,14 +43,12 @@ abstract class CopyJavadoc : DefaultTask() {
 
   init {
     // relative to project root, <output>/<projectName>/<projectVersion>
-    outputDir.set(rootDir.dir(output).flatMap { it.dir(this.projectName.map(this::filterProjectName)).flatMap { it.dir(this.projectVersion) } })
+    outputDir.set(rootDir.dir(output).flatMap { it.dir(this.projectName).flatMap { it.dir(this.projectVersion) } })
   }
 
   @TaskAction
   fun doTransfer() {
-    val dest = outputDir.get().asFile // rootDir.get().asFile.resolve(this.output.get())
-      // .resolve(this.filterProjectName(this.projectName.get()))
-      //.resolve(this.projectVersion.get())
+    val dest = outputDir.get().asFile
 
     dest.deleteRecursively()
     dest.mkdirs()
@@ -60,12 +58,4 @@ abstract class CopyJavadoc : DefaultTask() {
       into(dest)
     }
   }
-
-  private fun filterProjectName(name: String): String {
-    return if (name.startsWith(ADVENTURE_PREFIX)) {
-      name.substring(ADVENTURE_PREFIX.length, name.length)
-    } else {
-      name
-    }
-  }
 }

build-logic/src/main/kotlin/JavadocPackaging.kt

@@ -0,0 +1,11 @@
+import org.gradle.api.Named
+import org.gradle.api.attributes.Attribute
+
+interface JavadocPackaging : Named {
+  companion object {
+    val ATTRIBUTE = Attribute.of("net.kyori.javadoc.packaging", JavadocPackaging::class.java)
+
+    const val ARCHIVE = "archive"
+    const val DIRECTORY = "directory"
+  }
+}

build-logic/src/main/kotlin/adventure.common-conventions.gradle.kts

@@ -13,8 +13,41 @@ testlogger {
   showPassed = false
 }
 
-configurations.testCompileClasspath {
-  exclude(group = "junit") // brought in by google's libs
+configurations {
+  testCompileClasspath {
+    exclude(group = "junit") // brought in by google's libs
+  }
+
+  // Register unpacked Javadoc as an artifact for cross-linking
+  javadocElements {
+    outgoing {
+      variants {
+        create("files") {
+          artifact(tasks.javadoc.map { it.destinationDir!! }) {
+            builtBy(tasks.javadoc)
+          }
+          attributes {
+            attribute(JavadocPackaging.ATTRIBUTE, objects.named(JavadocPackaging.DIRECTORY))
+          }
+        }
+      }
+    }
+  }
+}
+
+// Resolve JD for cross-linking between modules
+val offlineLinkedJavadoc = configurations.register("offlineLinkedJavadoc") {
+  isCanBeResolved = true
+  isCanBeConsumed = false
+
+  attributes {
+    attribute(Category.CATEGORY_ATTRIBUTE, objects.named(Category.DOCUMENTATION))
+    attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling.EXTERNAL))
+    attribute(DocsType.DOCS_TYPE_ATTRIBUTE, objects.named(DocsType.JAVADOC))
+    attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage.JAVA_RUNTIME))
+    attribute(JavadocPackaging.ATTRIBUTE, objects.named(JavadocPackaging.DIRECTORY))
+  }
+  extendsFrom(configurations.runtimeElements.get())
 }
 
 repositories {
@@ -23,6 +56,10 @@ repositories {
 }
 
 dependencies {
+  attributesSchema {
+    attribute(JavadocPackaging.ATTRIBUTE)
+  }
+
   annotationProcessor("ca.stellardrift:contract-validator:1.0.0") // https://github.com/zml2008/contract-validator
   api(platform(project(":adventure-bom")))
   checkstyle("ca.stellardrift:stylecheck:0.1")
@@ -35,14 +72,47 @@ dependencies {
   testImplementation("org.junit.jupiter:junit-jupiter-params")
 }
 
+fun filterProjectName(name: String): String {
+  return if (name.startsWith(ADVENTURE_PREFIX)) {
+    name.substring(ADVENTURE_PREFIX.length, name.length)
+  } else {
+    name
+  }
+}
+
 tasks {
+  // link to modules in project
+  val jdLinks = offlineLinkedJavadoc.get().incoming
+    .artifactView {
+      componentFilter { it is ProjectComponentIdentifier } // only in-project
+      isLenient = true // ignore artifacts with no javadoc elements variant
+    }
+  val version = project.version
   javadoc {
+    inputs.property("project.version", version)
+    inputs.files(jdLinks.files)
+      .ignoreEmptyDirectories()
+      .withPropertyName("jdLinks")
+
     val options = options as? StandardJavadocDocletOptions ?: return@javadoc
     options.tags("sinceMinecraft:a:Since Minecraft:")
+
+    doFirst {
+      jdLinks.artifacts.forEach {
+        val file = it.file
+        val projectName = (it.id.componentIdentifier as ProjectComponentIdentifier).projectName
+        if (!file.isDirectory) {
+          logger.warn("Failed to link to Javadoc in $file (for $projectName) because it was not a directory")
+        }
+
+        // This matches the file structure in adventure-javadocs
+        options.linksOffline("../../${filterProjectName(projectName)}/$version", file.absolutePath)
+      }
+    }
   }
 
   register("copyJavadoc", CopyJavadoc::class) {
-    projectName.set(provider { project.name })
+    projectName.set(provider { filterProjectName(project.name) })
     projectVersion.set(provider { project.version.toString() })
     javadocFiles.from(javadoc)
     rootDir.set(project.rootDir)