HADOOP-7856. Improve DiskChecker javadocs.

[sankalpsthakur]

Fixes HADOOP-7856

Description of PR

DiskChecker#checkDir(File) javadocs were incomplete (the original summary trailed off, and later checkstyle-only @param/@throws text did not describe the method). Switching between checkDir(File) and checkDir(LocalFileSystem, Path, FsPermission) can also surprise callers: File-based access checks reflect OS/filesystem writability, while Hadoop FsPermission / FsAction#implies only inspect permission bits and can pass on a read-only filesystem.

This change completes the checkDir javadocs and calls that distinction out explicitly. After HADOOP-8973 both overloads also use File methods for access; the FsPermission overload still additionally applies expected permission, so the two APIs remain not equivalent.

Javadoc-only. No code behavior change.

How was this patch tested?

Host unit tests (OpenJDK 21, ./mvnw -pl hadoop-common-project/hadoop-common -am test -Dtest=TestDiskChecker,TestDiskCheckerWithDiskIo -Dmaven.test.failure.ignore=false):

• TestDiskChecker: Tests run: 14, Failures: 0, Errors: 0, Skipped: 0
• TestDiskCheckerWithDiskIo: Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
• Combined: Tests run: 19, Failures: 0, Errors: 0, Skipped: 0 (BUILD SUCCESS)

Javadoc-only change; no runtime behavior change. Apache Yetus (continuous-integration/jenkins/pr-merge) should run on this PR. The GitHub Actions Build workflow may wait for maintainer approval on first-time fork PRs (ACTION_REQUIRED).

For code changes:

• Does the title of this PR start with the corresponding JIRA issue id (e.g. 'HADOOP-17799. Your PR title ...')?
• Object storage: N/A
• New dependencies: none
• LICENSE/NOTICE: N/A

AI Tooling

• The PR includes the phrase "Contains content generated by Cursor Grok 4.6"
• My use of AI contributions follows the ASF legal policy https://www.apache.org/legal/generative-tooling.html

Contains content generated by Cursor Grok 4.6.

Contributor notes

• Apache ICLA may be required for this contribution. I am not claiming that an ICLA has been signed.
• Please do not merge until a committer has confirmed CLA status and reviewed the change.

[hadoop-yetus]

💔 -1 overall

Vote	Subsystem	Runtime	Logfile	Comment
+0 🆗	reexec	0m 22s		Docker mode activated.
			_ Prechecks _
+1 💚	dupname	0m 0s		No case conflicting files found.
+0 🆗	codespell	0m 0s		codespell was not available.
+0 🆗	detsecrets	0m 0s		detect-secrets 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.
			_ trunk Compile Tests _
+1 💚	mvninstall	27m 8s		trunk passed
+1 💚	compile	8m 43s		trunk passed with JDK Ubuntu-21.0.12+8-1-24.04-Ubuntu
+1 💚	compile	8m 56s		trunk passed with JDK Ubuntu-17.0.20+8-1-24.04-Ubuntu
+1 💚	checkstyle	0m 55s		trunk passed
+1 💚	mvnsite	1m 6s		trunk passed
+1 💚	javadoc	0m 50s		trunk passed with JDK Ubuntu-21.0.12+8-1-24.04-Ubuntu
+1 💚	javadoc	0m 52s		trunk passed with JDK Ubuntu-17.0.20+8-1-24.04-Ubuntu
-1 ❌	spotbugs	1m 49s	/branch-spotbugs-hadoop-common-project_hadoop-common-warnings.html	hadoop-common-project/hadoop-common in trunk has 1 extant spotbugs warnings.
+1 💚	shadedclient	16m 51s		branch has no errors when building and testing our client artifacts.
			_ Patch Compile Tests _
+1 💚	mvninstall	0m 42s		the patch passed
+1 💚	compile	8m 18s		the patch passed with JDK Ubuntu-21.0.12+8-1-24.04-Ubuntu
+1 💚	javac	8m 18s		the patch passed
+1 💚	compile	8m 56s		the patch passed with JDK Ubuntu-17.0.20+8-1-24.04-Ubuntu
+1 💚	javac	8m 56s		the patch passed
+1 💚	blanks	0m 0s		The patch has no blanks issues.
+1 💚	checkstyle	0m 48s		hadoop-common-project/hadoop-common: The patch generated 0 new + 6 unchanged - 1 fixed = 6 total (was 7)
+1 💚	mvnsite	1m 6s		the patch passed
+1 💚	javadoc	0m 52s		the patch passed with JDK Ubuntu-21.0.12+8-1-24.04-Ubuntu
+1 💚	javadoc	0m 53s		the patch passed with JDK Ubuntu-17.0.20+8-1-24.04-Ubuntu
+1 💚	spotbugs	1m 52s		the patch passed
+1 💚	shadedclient	16m 58s		patch has no errors when building and testing our client artifacts.
			_ Other Tests _
+1 💚	unit	18m 18s		hadoop-common in the patch passed.
+1 💚	asflicense	0m 45s		The patch does not generate ASF License warnings.
		128m 14s

Subsystem	Report/Notes
Docker	ClientAPI=1.56 ServerAPI=1.56 base: https://ci-hadoop.apache.org/job/hadoop-multibranch/job/PR-8746/1/artifact/out/Dockerfile
GITHUB PR	#8746
Optional Tests	dupname asflicense compile javac javadoc mvninstall mvnsite unit shadedclient spotbugs checkstyle codespell detsecrets
uname	Linux f28e52445024 5.15.0-190-generic #200-Ubuntu SMP Fri Aug 7 15:06:04 UTC 2026 x86_64 x86_64 x86_64 GNU/Linux
Build tool	maven
Personality	dev-support/bin/hadoop.sh
git revision	trunk / 1795838
Default Java	Ubuntu-17.0.20+8-1-24.04-Ubuntu
Multi-JDK versions	/usr/lib/jvm/java-21-openjdk-amd64:Ubuntu-21.0.12+8-1-24.04-Ubuntu /usr/lib/jvm/java-17-openjdk-amd64:Ubuntu-17.0.20+8-1-24.04-Ubuntu
Test Results	https://ci-hadoop.apache.org/job/hadoop-multibranch/job/PR-8746/1/testReport/
Max. process+thread count	3159 (vs. ulimit of 10000)
modules	C: hadoop-common-project/hadoop-common U: hadoop-common-project/hadoop-common
Console output	https://ci-hadoop.apache.org/job/hadoop-multibranch/job/PR-8746/1/console
versions	git=2.43.0 maven=3.9.15 spotbugs=4.9.7
Powered by	Apache Yetus 0.14.1 https://yetus.apache.org

This message was automatically generated.