[java] shrink published javadoc jars

[titusfortner]

🔗 Related Issues

While investigating why the 4.48.0 release failed package verification, I found org.seleniumhq is over Sonatype's monthly publishing limit with a single release.

💥 What does this PR do?

• Published javadoc jars no longer bundle the DejaVu web fonts, which were about 62% of a Selenium release.
• The generated CDP binding artifacts publish a stub javadoc jar instead of ~10 MB of generated pages each.

These changes will take the release size (including htmlunit driver) from ~165 MB to ~55 MB.
@rbri if we release htmlunit3-driver without bundling the dependencies we can drop that to ~28 MB per release.

🔧 Implementation Notes

• Javadoc bundles 3.85 MB of DejaVu fonts into every jar it generates and a release ships 22 of them; the stylesheet's font stacks fall back to Arial/Georgia/monospace, so dropping them only changes typography on javadoc.io.
• The Java API docs published to gh-pages do not rely on javadoc jars and are completely unaffected by these changes.
• The Java API docs we publish already exclude the CDP classes, so javadoc.io was the only place they were published and stubbing removes them there too.
• Stubbing CDP has no impact on IDEs, which render documentation from the sources jar.

🤖 AI assistance

• No substantial AI assistance used
• AI assisted (complete below)
  • Tool(s): Claude Code (Opus 5)
  • What was generated: the build changes, and the size analysis that traced the release payload to bundled fonts
  • I reviewed all AI output and can explain the change

💡 Additional Considerations

Options for saving space. Rows marked * are what this PR does.

Options	space saved
* fonts dropped from javadoc jars	84.8 MB
htmlunit3-driver does not include jar-with-dependencies	27.2 MB
* CDP javadoc stubbed	24.6 MB
CDP javadoc options reduced instead of stubbed	11.6 MB
CDP sources stubbed	4.8 MB
Package two CDP versions instead of three	1.7 MB

Note: #17586 will probably add back another ~4 MB

🔄 Types of changes

• Bug fix (backwards compatible)

[qodo-code-review]

PR Summary by Qodo

Shrink Java Javadoc artifacts by omitting fonts and stubbing CDP docs

🐞 Bug fix ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Omits bundled fonts from generated Javadoc jars to reduce every Java release artifact.
• Publishes minimal Javadoc jars for generated CDP bindings while retaining source-based IDE
 documentation.
• Reduces the release payload from roughly 165 MB to 55 MB.

Diagram

graph TD
  A["Java exports"] --> B["java_export macro"] --> C["Font-free Javadoc"] --> E["Compact docs jar"] --> F["Maven publish"]
  B --> D["CDP stub jar"] --> E

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Generate reduced CDP Javadoc

• ➕ Preserves browsable generated CDP API pages on javadoc.io
• ➕ Avoids publishing an intentionally minimal documentation artifact
• ➖ Saves substantially less space than stubbing
• ➖ Continues spending release quota on generated documentation already available from sources

2. Strip fonts after Javadoc generation

• ➕ Could preserve existing Javadoc invocation defaults
• ➕ Centralizes archive rewriting independently of JDK option support
• ➖ Adds a post-processing step and archive complexity
• ➖ Is less direct than the supported --no-fonts option

Recommendation: Use the PR's split strategy: the supported --no-fonts option is the simplest way to shrink ordinary Javadoc, while stubbing generated CDP documentation provides the largest quota reduction without affecting source jars or IDE rendering. Reduced CDP generation remains reasonable only if javadoc.io coverage is considered more valuable than the additional release size.

Files changed (7) +39 / -6

Bug fix (1) +26 / -6

export.bzlAdd compact and stub Javadoc publication paths +26/-6

Add compact and stub Javadoc publication paths

• Adds an opt-in stub_javadoc mode that packages a minimal index page instead of generated API documentation. Normal exports now pass --no-fonts while preserving the existing Javadoc options and Maven classifier wiring.

java/private/export.bzl

Documentation (1) +8 / -0

stub-javadoc.htmlProvide an explanatory stub documentation page +8/-0

Provide an explanatory stub documentation page

• Adds the index page used by stub Javadoc jars, directing consumers to source jars for documentation comments and IDE rendering.

java/private/stub-javadoc.html

Other (5) +5 / -0

BUILD.bazelExport the shared stub Javadoc page +1/-0

Export the shared stub Javadoc page

• Makes the stub HTML file publicly available to Bazel targets so the export macro can package it into Javadoc jars.

java/private/BUILD.bazel

BUILD.bazelStub Javadoc for the latest CDP artifact +1/-0

Stub Javadoc for the latest CDP artifact

• Opts the generated selenium-devtools-latest Maven artifact into minimal Javadoc publication.

java/src/org/openqa/selenium/devtools/latest/BUILD.bazel

BUILD.bazelStub Javadoc for CDP v150 +1/-0

Stub Javadoc for CDP v150

• Opts the generated selenium-devtools-v150 Maven artifact into minimal Javadoc publication.

java/src/org/openqa/selenium/devtools/v150/BUILD.bazel

BUILD.bazelStub Javadoc for CDP v151 +1/-0

Stub Javadoc for CDP v151

• Opts the generated selenium-devtools-v151 Maven artifact into minimal Javadoc publication.

java/src/org/openqa/selenium/devtools/v151/BUILD.bazel

BUILD.bazelStub Javadoc for CDP v152 +1/-0

Stub Javadoc for CDP v152

• Opts the generated selenium-devtools-v152 Maven artifact into minimal Javadoc publication.

java/src/org/openqa/selenium/devtools/v152/BUILD.bazel

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[rbri]

@titusfortner will have a look

[rbri]

@titusfortner had a first look at this, but the deploy plugins exclude feature seem not to work. Have opened a ticket, will inform you about the progress. For the weekend i plan an HtmlUnit/driver release, hope to have at least a workaround in place until then.

Thanks for the headsup....

[rbri]

@titusfortner found a solution the next release (this weekend) will no longer deploy the file jar-with-dependencies (will only make it available from the github release page.

Again thanks....

[qodo-code-review]

No code changes since the last review — review skipped