substrait-io · mbwhite · Dec 17, 2025 · Jan 5, 2026 · Jan 5, 2026 · Jan 7, 2026
diff --git a/core/build.gradle.kts b/core/build.gradle.kts
@@ -273,3 +273,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}/core/src/main/javadoc/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"))
+}
diff --git a/core/src/main/java/io/substrait/extension/DefaultExtensionCatalog.java b/core/src/main/java/io/substrait/extension/DefaultExtensionCatalog.java
@@ -52,6 +52,7 @@ public class DefaultExtensionCatalog {
 
   /** Extension identifier for string functions. */
   public static final String FUNCTIONS_STRING = "extension:io.substrait:functions_string";
+
   public static final String EXTENSION_TYPES = "extension:io.substrait:extension_types";
 
   /** Default collection of built-in extensions loaded from YAML resources. */

diff --git a/core/src/main/java/io/substrait/package-info.java b/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;
diff --git a/core/src/main/javadoc/overview.html b/core/src/main/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 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>
diff --git a/examples/substrait-spark/src/main/java/io/substrait/examples/util/SubstraitStringify.java b/examples/substrait-spark/src/main/java/io/substrait/examples/util/SubstraitStringify.java
@@ -72,9 +72,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) {
@@ -94,9 +94,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) {

diff --git a/isthmus/build.gradle.kts b/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"))
+}
diff --git a/substrait b/substrait
+1 −3		.flake8
+0 −2		.gitattributes
+1 −1		.github/CODEOWNERS
+1 −1		.github/workflows/licence_check.yml
+33 −24		.github/workflows/pr.yml
+1 −1		.github/workflows/pr_breaking.yml
+1 −1		.github/workflows/pr_title.yml
+2 −2		.github/workflows/release.yml
+1 −1		.github/workflows/site.yml
+0 −24		.github/workflows/stale.yml
+0 −35		CHANGELOG.md
+2 −2		CODE_OF_CONDUCT.md
+0 −14		CONTRIBUTING.md
+1 −2		extensions/functions_comparison.yaml
+0 −43		extensions/functions_list.yaml
+0 −1		grammar/FuncTestCaseLexer.g4
+42 −87		grammar/FuncTestCaseParser.g4
+0 −2		grammar/SubstraitLexer.g4
+0 −6		grammar/SubstraitType.g4
+8 −65		proto/substrait/algebra.proto
+1 −1		proto/substrait/extensions/extensions.proto
+0 −17		proto/substrait/type.proto
+1 −6		pyproject.toml
+1 −2		requirements.txt
+2 −2		site/data/committers.yaml
+0 −2		site/data/smc.yaml
+0 −7		site/docs/expressions/field_references.md
+0 −137		site/docs/expressions/lambda_expressions.md
+3 −3		site/docs/expressions/scalar_functions.md
+22 −2		site/docs/expressions/user_defined_functions.md
+40 −26		site/docs/extensions/index.md
+15 −15		site/docs/governance.md
+9 −20		site/docs/relations/logical_relations.md
+6 −6		site/docs/relations/physical_relations.md
+9 −4		site/docs/serialization/binary_serialization.md
+62 −30		site/docs/types/type_classes.md
+0 −18		site/docs/types/type_parsing.md
+0 −28		site/examples/README.md
+0 −11		site/examples/extensions/any1_type_function.yaml
+0 −11		site/examples/extensions/any_type_function.yaml
+0 −13		site/examples/extensions/distance_functions.yaml
+0 −22		site/examples/extensions/double_function.yaml
+0 −22		site/examples/extensions/lambda_function_example.yaml
+0 −11		site/examples/proto-textformat/README.md
+0 −32		site/examples/proto-textformat/field_reference/lambda_param_nested_struct.textproto
+0 −22		site/examples/proto-textformat/lambda/nested_lambda_capture.textproto
+0 −49		site/examples/proto-textformat/lambda/simple_multiply.textproto
+0 −66		site/examples/proto-textformat/lambda_invocation/inline_invocation.textproto
+0 −10		site/examples/types/point_with_datatype_param.yaml
+0 −10		site/examples/types/point_with_enum_param.yaml
+0 −5		site/examples/types/point_with_nstruct.yaml
+0 −7		site/examples/types/point_with_structure.yaml
+0 −9		site/examples/types/point_with_two_params.yaml
+0 −9		site/examples/types/tuple_optional_variadic.yaml
+0 −8		site/examples/types/union_variadic.yaml
+0 −18		site/examples/types/user_defined_point.yaml
+0 −11		site/examples/types/vector_with_constraints.yaml
+0 −1		site/mkdocs.yml
+6 −36		tests/README.md
+14 −14		tests/baseline.json
+1 −0		tests/cases/comparison/equal.test
+0 −3		tests/cases/comparison/nullif.test
+0 −12		tests/cases/list/filter.test
+0 −11		tests/cases/list/transform.test
+575 −594		tests/coverage/antlr_parser/FuncTestCaseLexer.py
+1,514 −2,178		tests/coverage/antlr_parser/FuncTestCaseParser.py
+32 −113		tests/coverage/antlr_parser/FuncTestCaseParserListener.py
+16 −61		tests/coverage/antlr_parser/FuncTestCaseParserVisitor.py
+0 −1		tests/coverage/extensions.py
+1 −2		tests/coverage/nodes.py
+2 −55		tests/coverage/test_coverage.py
+16 −21		tests/coverage/visitor.py
+0 −65		tests/test_proto_example_validator.py
+318 −326		tests/type/antlr_parser/SubstraitLexer.py
+318 −326		tests/type/antlr_parser/SubstraitTypeLexer.py
+0 −27		tests/type/antlr_parser/SubstraitTypeListener.py
+474 −683		tests/type/antlr_parser/SubstraitTypeParser.py
+0 −15		tests/type/antlr_parser/SubstraitTypeVisitor.py