TEZ-4694 Add package-level Javadoc descriptions so generated API docs show a short summary for each package by lewismc · Pull Request #466 · apache/tez

lewismc · 2026-03-16T23:50:37Z

PR for TEZ-4694
Although this is a large PR is is fairly trivial.

Package-level Javadoc

Added short package descriptions to existing package-info.java files across tez-api, tez-common, tez-dag, tez-mapreduce, tez-runtime-library, and tez-javadoc-tools.
Introduced package-info.java for API packages that had none.

Javadoc

Fixed Javadoc warnings by escaping HTML in comments (e.g. &, <, <=) in tez-api, tez-runtime-library, and tez-mapreduce.

Build

Registered generated-sources (e.g. protobuf output) as compile source roots via build-helper-maven-plugin in tez-mapreduce, tez-runtime-library, tez-runtime-internals, and tez-dag.
Enabled forked compiler with increased memory for tez-mapreduce, tez-runtime-internals, and tez-dag to avoid missing .class file errors during test-compile.

Please check that the package visibility assignments are correct. Thank you for any review.

Regarding the test4tests -1 Vote I suppose we could add a plugin to Yetus which ensures a description exists for each package-info.java however I think this is overkill.

… show a short summary for each package

tez-yetus · 2026-03-17T02:11:14Z

💔 -1 overall

Vote	Subsystem	Runtime	Logfile	Comment
+0 🆗	reexec	3m 44s		Docker mode activated.
			_ Prechecks _
+1 💚	dupname	0m 0s		No case conflicting files found.
+0 🆗	detsecrets	0m 0s		detect-secrets was not available.
+0 🆗	xmllint	0m 0s		xmllint was not available.
+1 💚	@author	0m 0s		The patch does not contain any @author tags.
-1 ❌	test4tests	0m 0s		The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch.
			_ master Compile Tests _
+0 🆗	mvndep	2m 11s		Maven dependency ordering for branch
+1 💚	mvninstall	6m 56s		master passed
+1 💚	compile	4m 3s		master passed
+1 💚	checkstyle	3m 17s		master passed
+1 💚	javadoc	3m 16s		master passed
+0 🆗	spotbugs	1m 11s		tez-api in master has 545 extant spotbugs warnings.
+0 🆗	spotbugs	0m 31s		tez-common in master has 13 extant spotbugs warnings.
+0 🆗	spotbugs	0m 32s		tez-runtime-internals in master has 111 extant spotbugs warnings.
+0 🆗	spotbugs	0m 41s		tez-runtime-library in master has 235 extant spotbugs warnings.
+0 🆗	spotbugs	0m 35s		tez-mapreduce in master has 124 extant spotbugs warnings.
+0 🆗	spotbugs	0m 56s		tez-dag in master has 749 extant spotbugs warnings.
+0 🆗	spotbugs	0m 28s		tez-tools/tez-javadoc-tools in master has 3 extant spotbugs warnings.
+0 🆗	spotbugs	4m 2s		root in master has 1935 extant spotbugs warnings.
			_ Patch Compile Tests _
+0 🆗	mvndep	0m 10s		Maven dependency ordering for patch
+1 💚	mvninstall	4m 41s		the patch passed
+1 💚	codespell	0m 48s		No new issues.
+1 💚	compile	4m 32s		the patch passed
+1 💚	javac	4m 32s		the patch passed
+1 💚	blanks	0m 0s		The patch has no blanks issues.
+1 💚	checkstyle	2m 40s		the patch passed
+1 💚	javadoc	0m 37s		tez-api generated 0 new + 0 unchanged - 10 fixed = 0 total (was 10)
+1 💚	javadoc	0m 17s		tez-common in the patch passed.
+1 💚	javadoc	0m 15s		tez-runtime-internals in the patch passed.
+1 💚	javadoc	0m 22s		tez-runtime-library generated 0 new + 0 unchanged - 8 fixed = 0 total (was 8)
+1 💚	javadoc	0m 21s		tez-mapreduce generated 0 new + 0 unchanged - 1 fixed = 0 total (was 1)
+1 💚	javadoc	0m 17s		tez-dag in the patch passed.
+1 💚	javadoc	0m 15s		tez-javadoc-tools in the patch passed.
+1 💚	javadoc	0m 51s		root generated 0 new + 0 unchanged - 19 fixed = 0 total (was 19)
+1 💚	spotbugs	10m 10s		the patch passed
			_ Other Tests _
+1 💚	unit	2m 8s		tez-api in the patch passed.
+1 💚	unit	0m 31s		tez-common in the patch passed.
+1 💚	unit	0m 49s		tez-runtime-internals in the patch passed.
+1 💚	unit	4m 31s		tez-runtime-library in the patch passed.
+1 💚	unit	1m 7s		tez-mapreduce in the patch passed.
+1 💚	unit	5m 4s		tez-dag in the patch passed.
+1 💚	unit	0m 19s		tez-javadoc-tools in the patch passed.
+1 💚	unit	60m 39s		root in the patch passed.
+1 💚	asflicense	2m 23s		The patch does not generate ASF License warnings.
		140m 5s

Subsystem	Report/Notes
Docker	ClientAPI=1.54 ServerAPI=1.54 base: https://ci-hadoop.apache.org/job/tez-multibranch/job/PR-466/1/artifact/out/Dockerfile
GITHUB PR	#466
Optional Tests	dupname asflicense javac javadoc unit codespell detsecrets xmllint compile spotbugs checkstyle
uname	Linux 3a107fcff3c4 5.15.0-173-generic #183-Ubuntu SMP Fri Mar 6 13:29:34 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux
Build tool	maven
Personality	/home/jenkins/jenkins-home/workspace/tez-multibranch_PR-466/src/.yetus/personality.sh
git revision	master / `1e51e7d`
Default Java	Ubuntu-21.0.10+7-Ubuntu-124.04
Test Results	https://ci-hadoop.apache.org/job/tez-multibranch/job/PR-466/1/testReport/
Max. process+thread count	2109 (vs. ulimit of 5500)
modules	C: tez-api tez-common tez-runtime-internals tez-runtime-library tez-mapreduce tez-dag tez-tools/tez-javadoc-tools . U: .
Console output	https://ci-hadoop.apache.org/job/tez-multibranch/job/PR-466/1/console
versions	git=2.43.0 maven=3.8.7 spotbugs=4.9.3 codespell=2.4.1
Powered by	Apache Yetus 0.15.1 https://yetus.apache.org

This message was automatically generated.

tez-runtime-library/src/main/java/org/apache/tez/http/async/netty/package-info.java

tez-mapreduce/pom.xml

abstractdog · 2026-03-18T16:05:00Z

@lewismc : this is huge, thanks! left 2 minor comments

… show a short summary for each package

lewismc · 2026-03-18T20:21:39Z

Thanks for the review @abstractdog I made the changes.

tez-yetus · 2026-03-18T22:40:53Z

💔 -1 overall

Vote	Subsystem	Runtime	Logfile	Comment
+0 🆗	reexec	4m 8s		Docker mode activated.
			_ Prechecks _
+1 💚	dupname	0m 0s		No case conflicting files found.
+0 🆗	detsecrets	0m 0s		detect-secrets was not available.
+0 🆗	xmllint	0m 0s		xmllint was not available.
+1 💚	@author	0m 0s		The patch does not contain any @author tags.
-1 ❌	test4tests	0m 0s		The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch.
			_ master Compile Tests _
+0 🆗	mvndep	2m 13s		Maven dependency ordering for branch
+1 💚	mvninstall	7m 11s		master passed
+1 💚	compile	4m 1s		master passed
+1 💚	checkstyle	3m 16s		master passed
+1 💚	javadoc	3m 18s		master passed
+0 🆗	spotbugs	1m 12s		tez-api in master has 545 extant spotbugs warnings.
+0 🆗	spotbugs	0m 28s		tez-common in master has 13 extant spotbugs warnings.
+0 🆗	spotbugs	0m 34s		tez-runtime-internals in master has 111 extant spotbugs warnings.
+0 🆗	spotbugs	0m 44s		tez-runtime-library in master has 235 extant spotbugs warnings.
+0 🆗	spotbugs	0m 34s		tez-mapreduce in master has 124 extant spotbugs warnings.
+0 🆗	spotbugs	1m 1s		tez-dag in master has 749 extant spotbugs warnings.
+0 🆗	spotbugs	0m 26s		tez-tools/tez-javadoc-tools in master has 3 extant spotbugs warnings.
+0 🆗	spotbugs	3m 57s		root in master has 1935 extant spotbugs warnings.
			_ Patch Compile Tests _
+0 🆗	mvndep	0m 10s		Maven dependency ordering for patch
+1 💚	mvninstall	4m 14s		the patch passed
+1 💚	codespell	0m 48s		No new issues.
+1 💚	compile	3m 51s		the patch passed
+1 💚	javac	3m 51s		the patch passed
+1 💚	blanks	0m 0s		The patch has no blanks issues.
+1 💚	checkstyle	2m 42s		the patch passed
+1 💚	javadoc	0m 36s		tez-api generated 0 new + 0 unchanged - 10 fixed = 0 total (was 10)
+1 💚	javadoc	0m 18s		tez-common in the patch passed.
+1 💚	javadoc	0m 16s		tez-runtime-internals in the patch passed.
+1 💚	javadoc	0m 21s		tez-runtime-library generated 0 new + 0 unchanged - 8 fixed = 0 total (was 8)
+1 💚	javadoc	0m 21s		tez-mapreduce generated 0 new + 0 unchanged - 1 fixed = 0 total (was 1)
+1 💚	javadoc	0m 18s		tez-dag in the patch passed.
+1 💚	javadoc	0m 16s		tez-javadoc-tools in the patch passed.
+1 💚	javadoc	0m 51s		root generated 0 new + 0 unchanged - 19 fixed = 0 total (was 19)
+1 💚	spotbugs	9m 53s		the patch passed
			_ Other Tests _
+1 💚	unit	2m 4s		tez-api in the patch passed.
+1 💚	unit	0m 31s		tez-common in the patch passed.
+1 💚	unit	0m 46s		tez-runtime-internals in the patch passed.
+1 💚	unit	4m 29s		tez-runtime-library in the patch passed.
+1 💚	unit	1m 6s		tez-mapreduce in the patch passed.
+1 💚	unit	5m 2s		tez-dag in the patch passed.
+1 💚	unit	0m 17s		tez-javadoc-tools in the patch passed.
+1 💚	unit	60m 18s		root in the patch passed.
+1 💚	asflicense	2m 25s		The patch does not generate ASF License warnings.
		138m 52s

Subsystem	Report/Notes
Docker	ClientAPI=1.54 ServerAPI=1.54 base: https://ci-hadoop.apache.org/job/tez-multibranch/job/PR-466/2/artifact/out/Dockerfile
GITHUB PR	#466
Optional Tests	dupname asflicense javac javadoc unit codespell detsecrets xmllint compile spotbugs checkstyle
uname	Linux 66bc5a565493 5.15.0-173-generic #183-Ubuntu SMP Fri Mar 6 13:29:34 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux
Build tool	maven
Personality	/home/jenkins/jenkins-home/workspace/tez-multibranch_PR-466/src/.yetus/personality.sh
git revision	master / `c99e386`
Default Java	Ubuntu-21.0.10+7-Ubuntu-124.04
Test Results	https://ci-hadoop.apache.org/job/tez-multibranch/job/PR-466/2/testReport/
Max. process+thread count	1355 (vs. ulimit of 5500)
modules	C: tez-api tez-common tez-runtime-internals tez-runtime-library tez-mapreduce tez-dag tez-tools/tez-javadoc-tools . U: .
Console output	https://ci-hadoop.apache.org/job/tez-multibranch/job/PR-466/2/console
versions	git=2.43.0 maven=3.8.7 spotbugs=4.9.3 codespell=2.4.1
Powered by	Apache Yetus 0.15.1 https://yetus.apache.org

This message was automatically generated.

abstractdog

LGTM

TEZ-4694 Add package-level Javadoc descriptions so generated API docs…

1e51e7d

… show a short summary for each package

abstractdog reviewed Mar 18, 2026

View reviewed changes

tez-runtime-library/src/main/java/org/apache/tez/http/async/netty/package-info.java Outdated Show resolved Hide resolved

abstractdog reviewed Mar 18, 2026

View reviewed changes

tez-mapreduce/pom.xml Outdated Show resolved Hide resolved

TEZ-4694 Add package-level Javadoc descriptions so generated API docs…

c99e386

… show a short summary for each package

abstractdog self-requested a review March 19, 2026 06:38

abstractdog approved these changes Mar 19, 2026

View reviewed changes

abstractdog merged commit d2cfd25 into apache:master Mar 19, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

TEZ-4694 Add package-level Javadoc descriptions so generated API docs show a short summary for each package#466

TEZ-4694 Add package-level Javadoc descriptions so generated API docs show a short summary for each package#466
abstractdog merged 2 commits intoapache:masterfrom
lewismc:TEZ-4694

lewismc commented Mar 16, 2026 •

edited

Loading

Uh oh!

tez-yetus commented Mar 17, 2026

Uh oh!

Uh oh!

Uh oh!

abstractdog commented Mar 18, 2026

Uh oh!

lewismc commented Mar 18, 2026

Uh oh!

tez-yetus commented Mar 18, 2026

Uh oh!

abstractdog left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

lewismc commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Package-level Javadoc

Javadoc

Build

Uh oh!

tez-yetus commented Mar 17, 2026

Uh oh!

Uh oh!

Uh oh!

abstractdog commented Mar 18, 2026

Uh oh!

lewismc commented Mar 18, 2026

Uh oh!

tez-yetus commented Mar 18, 2026

Uh oh!

abstractdog left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lewismc commented Mar 16, 2026 •

edited

Loading