From 636e105d28418af086dbe62b27d8984ee283cb8d Mon Sep 17 00:00:00 2001 From: MBWhite Date: Wed, 17 Dec 2025 10:29:06 +0000 Subject: [PATCH 1/6] 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 --- core/build.gradle.kts | 64 +++++++++++++++++++ .../main/java/io/substrait/package-info.java | 4 ++ .../examples/util/SubstraitStringify.java | 1 - isthmus/build.gradle.kts | 26 ++++++++ overview.html | 22 +++++++ 5 files changed, 116 insertions(+), 1 deletion(-) create mode 100644 overview.html diff --git a/core/build.gradle.kts b/core/build.gradle.kts index df0f3f364..e6c3a42a2 100644 --- 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("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") { + 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("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/package-info.java b/core/src/main/java/io/substrait/package-info.java index a62caaf60..e90c4c332 100644 --- 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/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 index f932b8044..2ece26e9f 100644 --- 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 @@ -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 explain(io.substrait.plan.Plan plan) { diff --git a/isthmus/build.gradle.kts b/isthmus/build.gradle.kts index ad6ce6230..ca36c2c6a 100644 --- 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") { + 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("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/overview.html b/overview.html new file mode 100644 index 000000000..1bb905f8e --- /dev/null +++ b/overview.html @@ -0,0 +1,22 @@ + +
+

Core Substrait Java API

+

+ 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. +

+ +

Components

+
    +
  • core Core classes and interfaces
    • +
  • + core-protobuf The ProtoBuf wrapper + classes +
    • +
  • + Isthmus API Utility module that uses + Calcite to convert SQL to/from Substrait +
    • +
+ From 73aa491fb073b0be761750db9f22cf737bfceafc Mon Sep 17 00:00:00 2001 From: MBWhite Date: Mon, 5 Jan 2026 16:31:10 +0000 Subject: [PATCH 2/6] fix: review comments Signed-off-by: MBWhite --- .../sessions/kotlin-compiler-743613223953325844.salive | 0 .../io/substrait/examples/util/SubstraitStringify.java | 8 +++++--- 2 files changed, 5 insertions(+), 3 deletions(-) create mode 100644 build-logic/.kotlin/sessions/kotlin-compiler-743613223953325844.salive diff --git a/build-logic/.kotlin/sessions/kotlin-compiler-743613223953325844.salive b/build-logic/.kotlin/sessions/kotlin-compiler-743613223953325844.salive new file mode 100644 index 000000000..e69de29bb 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 index 2ece26e9f..88d8366d6 100644 --- 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,8 +72,10 @@ public SubstraitStringify() { } /** - * Explains the Sustrait plan + * Explains the Substrait plan * + * @param plan Substrait Plan + * * @return List of strings; typically these would then be logged or sent to stdout */ public static List explain(io.substrait.plan.Plan plan) { @@ -93,9 +95,9 @@ public static List 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 explain(io.substrait.relation.Rel rel) { From b6f3e0e921816828767671ee4a70c0f56ff5c92a Mon Sep 17 00:00:00 2001 From: MBWhite Date: Mon, 5 Jan 2026 16:31:47 +0000 Subject: [PATCH 3/6] fix: review comments Signed-off-by: MBWhite --- .../.kotlin/sessions/kotlin-compiler-743613223953325844.salive | 0 .../main/java/io/substrait/examples/util/SubstraitStringify.java | 1 - 2 files changed, 1 deletion(-) delete mode 100644 build-logic/.kotlin/sessions/kotlin-compiler-743613223953325844.salive diff --git a/build-logic/.kotlin/sessions/kotlin-compiler-743613223953325844.salive b/build-logic/.kotlin/sessions/kotlin-compiler-743613223953325844.salive deleted file mode 100644 index e69de29bb..000000000 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 index 88d8366d6..fa7207e9c 100644 --- 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 @@ -75,7 +75,6 @@ public SubstraitStringify() { * Explains the Substrait plan * * @param plan Substrait Plan - * * @return List of strings; typically these would then be logged or sent to stdout */ public static List explain(io.substrait.plan.Plan plan) { From a029bbf6114cb963afe383536b4ff6a6d8d2acea Mon Sep 17 00:00:00 2001 From: MBWhite Date: Wed, 7 Jan 2026 14:36:50 +0000 Subject: [PATCH 4/6] fix: review comments Signed-off-by: MBWhite --- overview.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/overview.html b/overview.html index 1bb905f8e..b090898d5 100644 --- a/overview.html +++ b/overview.html @@ -11,11 +11,11 @@

Components

From 4cb6f573db2a4a7eaf01c4b5f0771893ce945a56 Mon Sep 17 00:00:00 2001 From: MBWhite Date: Fri, 9 Jan 2026 09:46:41 +0000 Subject: [PATCH 5/6] fix: review comments Signed-off-by: MBWhite --- core/build.gradle.kts | 2 +- overview.html => core/src/main/javadoc/overview.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename overview.html => core/src/main/javadoc/overview.html (88%) diff --git a/core/build.gradle.kts b/core/build.gradle.kts index e6c3a42a2..8c9d549a5 100644 --- a/core/build.gradle.kts +++ b/core/build.gradle.kts @@ -321,7 +321,7 @@ tasks.named("javadoc") { encoding = "UTF-8" destinationDir = rootProject.layout.buildDirectory.dir("docs/${version}/core").get().asFile - addStringOption("overview", "${rootProject.projectDir}/overview.html") + addStringOption("overview", "${rootProject.projectDir}/core/src/main/javadoc/overview.html") addStringOption("link", "../core-proto") } } diff --git a/overview.html b/core/src/main/javadoc/overview.html similarity index 88% rename from overview.html rename to core/src/main/javadoc/overview.html index b090898d5..c75444241 100644 --- a/overview.html +++ b/core/src/main/javadoc/overview.html @@ -9,7 +9,7 @@

Core Substrait Java API

Components

    -
  • core Core classes and interfaces
    • +
  • core - Core classes and interfaces
  • core-protobuf - The Proto Buffers wrapper classes From bd4e0e939247d3130c68d3cbfc62bf8cde5d99a1 Mon Sep 17 00:00:00 2001 From: MBWhite Date: Wed, 14 Jan 2026 11:30:06 +0000 Subject: [PATCH 6/6] fix: resync with main Signed-off-by: MBWhite --- .../java/io/substrait/extension/DefaultExtensionCatalog.java | 1 + substrait | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/core/src/main/java/io/substrait/extension/DefaultExtensionCatalog.java b/core/src/main/java/io/substrait/extension/DefaultExtensionCatalog.java index eda4b3bb2..59690f438 100644 --- 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/substrait b/substrait index 92d2e757a..3c25b1b3e 160000 --- a/substrait +++ b/substrait @@ -1 +1 @@ -Subproject commit 92d2e757a330f9c973bb566817dc92afd1badcb2 +Subproject commit 3c25b1b3eaadecba6d10af6b3dd0fe038d0c5993