[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

Merging #491 (e21541f) into master (877b9e3) will increase coverage by 0.06%.
The diff coverage is 0.00%.

@@             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     

Files	Coverage Δ
...ain/java/org/apache/commons/io/file/PathUtils.java	72.16% <0.00%> (ø)

... and 2 files with indirect coverage changes

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[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?