fix: improve the javadoc generation

Make all components put javadoc into a consistent root.
This achieves the following

- means the javadoc for the generated protobuf can be
  kept quiet - as we can't adjust the javadoc here
- there is a single place for javadoc that could be published
- the isthmus and core and protobuf projects can be interlinked
- isthmus can be linked with the calcite javadoc
- overview pages can be added
- all under a versioned directory for easy maintence

To date there isn't (AFAIK) a stightforward maintainable way to
merge javadoc form multi-component projects

Signed-off-by: MBWhite <[email protected]>

Author: mbwhite

core/build.gradle.kts

@@ -272,3 +272,67 @@ protobuf {
   generateProtoTasks { all().configureEach { dependsOn(submodulesUpdate) } }
   protoc { artifact = "com.google.protobuf:protoc:" + libs.protoc.get().getVersion() }
 }
+
+val protoJavaDir = layout.buildDirectory.dir("generated/sources/proto/main/java")
+
+// First pass: Javadoc for generated protobufs — ignore warnings.
+tasks.register<Javadoc>("javadocProto") {
+  group = JavaBasePlugin.DOCUMENTATION_GROUP
+  description = "Generate Javadoc for protobuf-generated sources (warnings suppressed)."
+
+  // Only the generated proto sources
+  setSource(fileTree(protoJavaDir) { include("**/*.java") })
+
+  // Use the main source set classpath to resolve types referenced by the generated code
+  classpath = sourceSets["main"].compileClasspath
+
+  // Destination separate from main Javadoc
+  destinationDir = rootProject.layout.buildDirectory.dir("docs/${version}/core-proto").get().asFile
+
+  // Make sure protobufs are generated before Javadoc runs
+  dependsOn("generateProto")
+
+  // Suppress warnings/doclint for protobuf pass
+  (options as StandardJavadocDocletOptions).apply {
+    // Disable doclint entirely
+    addBooleanOption("Xdoclint:none", true)
+    // Be quiet
+    addBooleanOption("quiet", true)
+    // Encoding is good practice
+    encoding = "UTF-8"
+  }
+
+  // Do not fail the build if javadoc finds issues in generated sources
+  isFailOnError = false
+}
+
+// Second pass: Javadoc for main code, excluding the generated protobuf sources.
+tasks.named<Javadoc>("javadoc") {
+  mustRunAfter("javadocProto")
+  description = "Generate Javadoc for main sources (excludes protobuf-generated sources)."
+
+  // Exclude the protobuf-generated directory from the main pass
+  val protoDirFile = protoJavaDir.get().asFile
+  exclude { spec -> spec.file.toPath().startsWith(protoDirFile.toPath()) }
+
+  // Keep normal behavior for main javadoc (warnings allowed to show/fail if you want)
+  (options as StandardJavadocDocletOptions).apply {
+    encoding = "UTF-8"
+    destinationDir = rootProject.layout.buildDirectory.dir("docs/${version}/core").get().asFile
+
+    addStringOption("overview", "${rootProject.projectDir}/overview.html")
+    addStringOption("link", "../core-proto")
+  }
+}
+
+// Bundle both passes into the Javadoc JAR used for publishing.
+tasks.named<Jar>("javadocJar") {
+  val shared = rootProject.layout.buildDirectory.dir("docs/${version}").get().asFile
+  if (!shared.exists()) {
+    println("Creating a dir for javadoc ${rootProject.buildDir}/docs/${version}")
+    shared.mkdirs()
+  }
+
+  // Ensure both javadoc tasks have produced outputs
+  dependsOn(tasks.named("javadocProto"), tasks.named("javadoc"))
+}

core/src/main/java/io/substrait/package-info.java

@@ -1,2 +1,6 @@
+/**
+ * The {@code io.substrait} package provides core classes and interfaces for working with the
+ * Substrait specification, which defines a portable representation of query plans and expressions.
+ */
 @org.immutables.value.Value.Style(allowedClasspathAnnotations = {java.lang.Override.class})
 package io.substrait;

examples/substrait-spark/src/main/java/io/substrait/examples/util/SubstraitStringify.java

@@ -74,7 +74,6 @@ public SubstraitStringify() {
   /**
    * Explains the Sustrait plan
    *
-   * @param plan Subsrait plan
    * @return List of strings; typically these would then be logged or sent to stdout
    */
   public static List<String> explain(io.substrait.plan.Plan plan) {
@@ -96,7 +95,7 @@ public static List<String> explain(io.substrait.plan.Plan plan) {
   /**
    * Explains the Sustrait relation
    *
-   * @param plan Subsrait relation
+   * @param rel Subsrait relation
    * @return List of strings; typically these would then be logged or sent to stdout
    */
   public static List<String> explain(io.substrait.relation.Rel rel) {

isthmus/build.gradle.kts

@@ -147,3 +147,29 @@ tasks {
 sourceSets { test { proto.srcDirs("src/test/resources/extensions") } }
 
 protobuf { protoc { artifact = "com.google.protobuf:protoc:" + libs.protoc.get().getVersion() } }
+
+tasks.named<Javadoc>("javadoc") {
+  description = "Generate Javadoc for main sources (excludes protobuf-generated sources)."
+
+  // Keep normal behavior for main javadoc (warnings allowed to show/fail if you want)
+  (options as StandardJavadocDocletOptions).apply {
+    encoding = "UTF-8"
+    destinationDir = rootProject.layout.buildDirectory.dir("docs/${version}/isthmus").get().asFile
+
+    addStringOption("link", "../core-proto")
+    addStringOption("link", "../core")
+    addStringOption("link", "https://calcite.apache.org/javadocAggregate/")
+  }
+}
+
+// Bundle both passes into the Javadoc JAR used for publishing.
+tasks.named<Jar>("javadocJar") {
+  val shared = rootProject.layout.buildDirectory.dir("docs/${version}").get().asFile
+  if (!shared.exists()) {
+    println("Creating a dir for javadoc ${rootProject.buildDir}/${version}")
+    shared.mkdirs()
+  }
+
+  // Ensure javadoc tasks have produced output
+  dependsOn(tasks.named("javadoc"))
+}

overview.html

@@ -0,0 +1,22 @@
+<body>
+  <hr />
+  <h1>Core Substrait Java API</h1>
+  <p>
+    The {@code io.substrait} package provides core classes and interfaces for
+    working with the Substrait specification, which defines a portable
+    representation of query plans and expressions.
+  </p>
+
+  <h2>Components</h2>
+  <ul>
+    <li><a href="./index.html">core</a> Core classes and interfaces</li>
+    <li>
+      <a href="../core-proto/index.html">core-protobuf</a> The ProtoBuf wrapper
+      classes
+    </li>
+    <li>
+      <a href="../isthmus/index.html">Isthmus API</a> Utility module that uses
+      Calcite to convert SQL to/from Substrait
+    </li>
+  </ul>
+</body>