fix: improve the javadoc generation

core/build.gradle.kts

@@ -273,3 +273,113 @@ 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")
+
+val immuteableJavaDir = layout.buildDirectory.dir("generated/sources/annotationProcessor/java/main")
+
+// First pass: Javadoc for generated protobufs — ignore warnings.
+tasks.register<Javadoc>("javadocProto") {
+  dependsOn("generateProto", "compileJava")
+
+  group = JavaBasePlugin.DOCUMENTATION_GROUP
+  description = "Generate Javadoc for protobuf-generated sources (warnings suppressed)."
+
+  // Only the generated proto sources
+  setSource(fileTree(protoJavaDir) { include("**/*.java") })
+  // source(fileTree(immuteableJavaDir) { 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"
+    addStringOption(
+      "overview",
+      "${rootProject.projectDir}/core/src/main/javadoc/overview-proto.html",
+    )
+  }
+
+  // Do not fail the build if javadoc finds issues in generated sources
+  isFailOnError = false
+}
+
+tasks.register<Javadoc>("javadocImmutable") {
+  dependsOn("compileJava", "javadoc")
+
+  group = JavaBasePlugin.DOCUMENTATION_GROUP
+  description = "Generate Javadoc for immutable-generated sources (warnings suppressed)."
+
+  // Only the generated proto sources
+  setSource(fileTree(immuteableJavaDir) { include("**/*.java") })
+  // source(fileTree(immuteableJavaDir) { 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}/immutable").get().asFile
+
+  // 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"
+    addStringOption(
+      "overview",
+      "${rootProject.projectDir}/core/src/main/javadoc/overview-immutable.html",
+    )
+    links("../core/")
+    links("../core-proto/")
+  }
+
+  // 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") {
+  dependsOn("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()) }
+  source(fileTree(immuteableJavaDir) { include("**/*.java") })
+
+  // 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}/core/src/main/javadoc/overview.html")
+    links("../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"), tasks.named("javadocImmutable"))
+}

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;

core/src/main/javadoc/overview-proto.html

@@ -0,0 +1,24 @@
+<body>
+  <hr />
+  <h1>Core Substrait Protocol Buffers</h1>
+  <p>
+    This package contains the Protocol Buffer generated classes for the Substrait
+    specification. These classes provide the serialization format for Substrait
+    query plans and expressions, enabling cross-language and cross-platform
+    interoperability.
+  </p>
+
+  <h2>Components</h2>
+  <ul>
+    <li>
+      <a href="../core/index.html">core</a> - Core Substrait classes and interfaces
+    </li>
+    <li>
+      <a href="./index.html">core-protobuf</a> - The Proto Buffers 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>

core/src/main/javadoc/overview.html

@@ -0,0 +1,29 @@
+<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>
+
+    <p>
+    Also includes immutable value objects generated by the Immutables
+    annotation processor. These classes provide type-safe, immutable data structures
+    for working with Substrait concepts, ensuring thread safety and preventing
+    accidental mutations.
+  </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 Proto Buffers 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>

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

@@ -71,9 +71,9 @@ public SubstraitStringify() {
   }
 
   /**
-   * Explains the Sustrait plan
+   * Explains the Substrait plan
    *
-   * @param plan Subsrait plan
+   * @param plan Substrait 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) {
@@ -93,9 +93,9 @@ public static List<String> explain(io.substrait.plan.Plan plan) {
   }
 
   /**
-   * Explains the Sustrait relation
+   * Explains the Substrait relation
    *
-   * @param rel Subsrait relation
+   * @param rel Substrait 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,31 @@ tasks {
 sourceSets { test { proto.srcDirs("src/test/resources/extensions") } }
 
 protobuf { protoc { artifact = "com.google.protobuf:protoc:" + libs.protoc.get().getVersion() } }
+
+tasks.named<Javadoc>("javadoc") {
+  dependsOn(":core:javadoc", ":core:javadocProto")
+  description = "Generate Javadoc for main 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("overview", "${rootProject.projectDir}/isthmus/src/main/javadoc/overview.html")
+    links("../core-proto/")
+    links("../core/")
+    links("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"))
+}

isthmus/src/main/javadoc/overview.html

@@ -0,0 +1,21 @@
+<body>
+  <hr />
+  <h1>Isthmus - SQL to Substrait Converter</h1>
+  <p>
+    The {@code io.substrait.isthmus} package provides utilities for converting
+    between SQL and Substrait using Apache Calcite. Isthmus enables bidirectional
+    translation of SQL queries to Substrait plans and vice versa.
+  </p>
+
+  <h2>Components</h2>
+  <ul>
+    <li>
+      <a href="../core/index.html">core</a> - Core Substrait classes and interfaces
+    </li>
+    <li>
+      <a href="../core-proto/index.html">core-protobuf</a> - The Proto Buffers wrapper
+      classes
+    </li>
+    <li><a href="./index.html">Isthmus API</a> - SQL to/from Substrait conversion</li>
+  </ul>
+</body>