cloud-fan opened a new pull request, #55814:
URL: https://github.com/apache/spark/pull/55814
### What changes were proposed in this pull request?
After the noise filters from #55605, the Documentation generation CI log is
around 4K lines on a failure run. The two-line per-file `error: reference not
found` diagnostics are still buried in the middle of the log, and the GitHub
Actions check panel for a failed doc-gen job only surfaces `Process completed
with exit code 1`. Reviewers end up scrolling the raw log to find what actually
broke.
This PR is purely additive in `docs/_plugins/build_api_docs.rb` -- no
existing log lines are dropped. After the unidoc pipe closes:
1. A trailing `Fatal javadoc errors (N):` block is printed, listing each
captured diagnostic with file, line, and message.
2. One `::error file=<path>,line=<line>,title=javadoc::<msg>` GitHub Actions
workflow command is emitted per diagnostic, so they appear as inline
annotations on the PR check panel instead of as a single opaque `exit code 1`.
Diagnostics are captured strictly within the Standard Doclet phase bracketed
by `Building tree for all the packages and classes...` and `Building index for
all classes...`, which is where doclint emits the build-failing diagnostics
that count toward javadoc's exit code. Source-loading `error:` chatter outside
that window is excluded -- it's already non-fatal and matches what javadoc's
own `N errors` summary line counts.
As a self-check, the captured count is compared against javadoc's own `N
errors` summary line. If they diverge -- e.g. because a future JDK changes the
Standard Doclet phase wording -- a `::warning::` workflow command is emitted so
the drift is surfaced without silently masking real failures.
### Why are the changes needed?
PR #55605 made the doc-gen log small enough to read, but the failure path is
still discoverable only via grep. The per-file diagnostics emitted by doclint
are the actionable content; promoting them to the PR check panel and a clearly
delimited summary block makes a doc-gen failure self-explanatory without
leaving the PR.
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
End-to-end on this branch with deliberately broken references planted in two
code paths (mirroring the test pattern from PR #55605):
- `ColumnarMap.java` (real Java source): `{@link
org.apache.spark.deliberately.NoSuchClass}` and `{@link
ColumnVector#nonExistentMethod()}`.
- `Partition.scala` (Scala source via genjavadoc): `[[Partition.index]]` --
the `.`-separator case that javadoc treats as inner-class lookup.
The Documentation generation job will fail with the expected `Fatal javadoc
errors` summary block in the log and per-file inline annotations on this PR's
check panel. The plant commit will be dropped before this PR is taken out of
draft.
The state machine was also exercised locally against a captured log from a
prior failing doc-gen run; the captured fatal count matches javadoc's `N
errors` summary line.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Claude (Anthropic)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
