Skip to content

docs(scala): fully-qualify ScalaDoc @throws and link references#4671

Merged
Yicong-Huang merged 2 commits into
apache:mainfrom
Yicong-Huang:fix/scaladoc-broken-links
May 2, 2026
Merged

docs(scala): fully-qualify ScalaDoc @throws and link references#4671
Yicong-Huang merged 2 commits into
apache:mainfrom
Yicong-Huang:fix/scaladoc-broken-links

Conversation

@Yicong-Huang
Copy link
Copy Markdown
Contributor

What changes were proposed in this PR?

Resolve the ScalaDoc broken-link warnings tracked in #4670 by replacing bare class names with fully-qualified names in @throws tags and [[X]] inline links.

  • JDK exception references → java.lang.AssertionError, java.util.NoSuchElementException, java.lang.IllegalArgumentException, java.io.FileNotFoundException, java.lang.Exception, java.sql.SQLException, java.lang.reflect.AnnotatedType.
  • JAX-RS exception → javax.ws.rs.BadRequestException.
  • Project-internal references resolved against their companion objects: org.apache.texera.amber.core.tuple.AttributeTypeUtils.AttributeTypeException, org.apache.texera.service.resource.ComputingUnitManagingResource.DashboardWorkflowComputingUnit.
  • S3StorageClient.scala — Javadoc {@link software.amazon.awssdk...} references converted to ScalaDoc [[software.amazon.awssdk...]] form (the AWS SDK references are already on the classpath; ScalaDoc was rejecting the Javadoc syntax).
  • Vendored JsonSchemaInject.java — same-class method links {@link #json()} rewritten with explicit class context as {@link JsonSchemaInject#json()}.

@throws[X] annotations in code (Scala-level annotations, not docstring tags) are intentionally untouched — only the ScalaDoc * @throws X lines and [[X]] references in comments change.

Two extra docstring sites were swept up while at it (StableMergeSortOpExecSpec.scala, DatasetResource.scala) so the build does not start emitting new warnings the next time their modules' scaladoc runs.

Any related issues, documentation, discussions?

Closes #4670.

How was this PR tested?

Pure ScalaDoc / comment changes — no behavioral effect, no test changes. Verified by:

  1. `grep -r '@throws AssertionError' --include='*.scala'` and the same for the other 8 bare class names returns zero hits across the repo.
  2. CI's scala job runs scaladoc as part of `sbt jacoco` / compile and will report any remaining unresolved references.

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Opus 4.7, 1M context)

Resolve 29+ scaladoc broken-link warnings by replacing bare class
names in @throws tags and [[X]] inline links with their fully-
qualified names. JDK exceptions go to java.lang/java.io/java.util/
java.sql; project-internal types use their full package + companion
object path. AWS SDK references in S3StorageClient switch from
Javadoc {@link X} to Scaladoc [[X]] form. Vendored JsonSchemaInject.java
gains explicit class context on its method links.

Closes apache#4670.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented May 2, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.02%. Comparing base (8841990) to head (3ed2969).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@             Coverage Diff              @@
##               main    #4671      +/-   ##
============================================
+ Coverage     52.46%   53.02%   +0.55%     
- Complexity        0     1994    +1994     
============================================
  Files           353      817     +464     
  Lines         21338    24630    +3292     
  Branches       1791     1921     +130     
============================================
+ Hits          11195    13060    +1865     
- Misses        10026    10914     +888     
- Partials        117      656     +539     
Flag Coverage Δ
agent-service ?
frontend ?
python 85.05% <ø> (ø)
scala 38.17% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Yicong-Huang Yicong-Huang requested a review from aglinxinyuan May 2, 2026 09:13
Copy link
Copy Markdown
Contributor

@aglinxinyuan aglinxinyuan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@Yicong-Huang Yicong-Huang enabled auto-merge (squash) May 2, 2026 09:22
@Yicong-Huang Yicong-Huang merged commit 34a00cc into apache:main May 2, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Fix 29 ScalaDoc broken-link warnings in Scala build

3 participants