[IO-814] Don't throw UncheckedIOException

[elharo]

Fortunately the API here offered a backwards compatible fix. Since it was already declared to return null for some exceptions, this makes it return null for IOException too. This reverts the behavior breaking change without adding any API changes to anyone's code.

Also some javadoc cleanups while I was in here.

[garydgregory]

Please don't change the style: Sentences start with a capital letter and end with a period.

[elharo]

Except they aren't sentences. They're sentence fragments, and this case is explicitly called out in the Oracle style guidelines: "When writing the comments themselves, in general, start with a phrase and follow it with sentences if they are needed. When writing a phrase, do not capitalize and do not end with a period".

If the project wants to diverge from that, it's worth calling it out explicitly in a project specific style guide.

[garydgregory]

Except they aren't sentences. They're sentence fragments, and this case is explicitly called out in the Oracle style guidelines: "When writing the comments themselves, in general, start with a phrase and follow it with sentences if they are needed. When writing a phrase, do not capitalize and do not end with a period".

If the project wants to diverge from that, it's worth calling it out explicitly in a project specific style guide.

We do, under a header called "Respect The Original Style" on https://commons.apache.org/patches.html

I suppose it could go into more detail of course ;-)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.03%. Comparing base (877b9e3) to head (e21541f).
⚠️ Report is 1750 commits behind head on master.

Files with missing lines	Patch %	Lines
...ain/java/org/apache/commons/io/file/PathUtils.java	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master     #491      +/-   ##
============================================
+ Coverage     84.97%   85.03%   +0.06%     
- Complexity     3372     3375       +3     
============================================
  Files           227      227              
  Lines          8080     8080              
  Branches        953      953              
============================================
+ Hits           6866     6871       +5     
+ Misses          960      957       -3     
+ Partials        254      252       -2     

☔ 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.

[elharo]

Reverted Javadoc nits. PTAL

[jglick]

Would a variant of the test from #478 be useful here as a regression test? Like

PathUtils.deleteFile(tempDir.resolve("nonexistent").resolve("file-does-not-exist.bin"), StandardDeleteOption.OVERRIDE_READ_ONLY));

which if I understand correctly should now return normally?