[IO-836] Update FileNameUtils Javadoc

[elharo]

@garydgregory I read through the entire class to to figure out its intent and I think the edits here —which are purely to doc comments, not to code — somewhat help to explain that.

Having said that, this class has some issues, including using a lot of non-standard terminology and probably some bugs on edge conditions. This will require additional PRs for code and tests.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.99%. Comparing base (511a95a) to head (448394e).
⚠️ Report is 1450 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##             master     #554   +/-   ##
=========================================
  Coverage     85.99%   85.99%           
  Complexity     3492     3492           
=========================================
  Files           231      231           
  Lines          8246     8246           
  Branches        962      962           
=========================================
  Hits           7091     7091           
  Misses          865      865           
  Partials        290      290           

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