docs(path): improve API docs

[kt3k]

part of #4600 #3764

supercedes #4839

[codecov]

Codecov Report

Attention: Patch coverage is 92.30769% with 3 lines in your changes are missing coverage. Please review.

Project coverage is 92.12%. Comparing base (079e402) to head (5e1bd64).
Report is 20 commits behind head on main.

Files	Patch %	Lines
path/constants.ts	50.00%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4900      +/-   ##
==========================================
+ Coverage   92.02%   92.12%   +0.09%     
==========================================
  Files         488      487       -1     
  Lines       38900    38772     -128     
  Branches     5395     5388       -7     
==========================================
- Hits        35797    35717      -80     
+ Misses       3047     2999      -48     
  Partials       56       56              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[iuioiua]

I see quite a few instances of improper casing and partial sentences. Can you please fix those?

[iuioiua]

I've fixed quite a few nits and added a few improvements. Though, I think there's a bit more work to do here:

1. Mention the differences in behavior for OS-dependent APIs.
2. Add ../path/posix/mod.ts and ../path/windows/mod.ts to the Super Linter, and document everything in those directories. We should get top-level documentation to a good state, then just copy the relevant details over.
3. Improve the example code snippets (see suggestion).

[iuioiua]

Big win! Great work!