doc: path.format provide more examples

[eversojk]

Pull Request check-list

• Does make -j8 test (UNIX) or vcbuild test nosign (Windows) pass with
  this change (including linting)?
• Is the commit message formatted according to [CONTRIBUTING.md][0]?
• If this change fixes a bug (or a performance problem), is a regression
  test (or a benchmark) included?
• Is a documentation update included (if this change modifies
  existing APIs, or introduces new ones)?

Affected core subsystem(s)

path

Description of change

Added examples for all cases of path.format for V5.9.0 on Linux.

Fixes #5747

[eversojk]

I've run the tests to get into the habit of doing so and seem to be getting an error unrelated to any of my changes. If someone could confirm they are seeing something similar I'd be happy to create an issue.

make jslint
make[1]: Entering directory '/home/john/projects/node'
./node tools/eslint/bin/eslint.js benchmark lib src test tools/doc \
        tools/eslint-rules --rulesdir tools/eslint-rules

/home/john/projects/node/benchmark/http_simple_auto.js
  16:13  error  Strings must use singlequote  quotes
  35:19  error  Strings must use singlequote  quotes
  44:12  error  'i' is not defined            no-undef
  44:19  error  'i' is not defined            no-undef
  44:26  error  'i' is not defined            no-undef
  45:25  error  'i' is not defined            no-undef
  77:10  error  'i' is not defined            no-undef
  77:37  error  'i' is not defined            no-undef
  77:46  error  'i' is not defined            no-undef
  78:28  error  'i' is not defined            no-undef
  78:38  error  'i' is not defined            no-undef

✖ 11 problems (11 errors, 0 warnings)

Makefile:596: recipe for target 'jslint' failed
make[1]: *** [jslint] Error 1
make[1]: Leaving directory '/home/john/projects/node'
Makefile:115: recipe for target 'test' failed
make: *** [test] Error 2

[eversojk]

Ready for review

[Trott]

Regarding the benchmark tests failing lint, not your problem, it's #5359. I'll put together a fix now unless someone beats me to it.

[Trott]

The fix has landed, so if you do a rebase against master, it should clear up the linting issue you had.

[Trott]

OK, so looking at the change you made here, it's all correct, but I think it would be better to format the changes as if the pathObject were the output of path.parse() (just mangled appropriately by removing properties as needed for each example).

So, for example, the value of root will always be / and the value of dir will never have a trailing slash.

> path.parse('/home/user/dir/file.txt')
{ root: '/',
  dir: '/home/user/dir',
  base: 'file.txt',
  ext: '.txt',
  name: 'file' }
> 

So maybe start with that output above and just delete properties as needed (and update your results, of course, as needed)?

Is that clear? I hope I'm making sense...

[eversojk]

Makes perfect sense, I'll add in those changes.

[eversojk]

I've updated with your suggestions. I used /home/user/dir/file.txt for all examples except to trigger the scenario where dir === root which I used /file.txt.

Would it be preferred that I squash all of my commits and explain what my change is in the squashed commit before having you review?

[Trott]

Now is probably a good time to squash, yes.

[Trott]

Nit: Would it help to put a period at the end of this line and the one above to make it clear that the subsequent line is a new sentence?

[Trott]

LGTM with nits that can be ignored if you disagree with them.

[eversojk]

I agree with the nits, I debated doing that.

[eversojk]

Nits updated and commits squashed.

[Trott]

/cc @nodejs/documentation

[jasnell]

LGTM

[Trott]

LGTM

Nit: Might as well add periods to the end of all the comment sentences and capitalize the first word (where it's not the name of a property!) for consistency. (And if not, then oh well, it will make a nice good first commit for someone else.)

[nwoltman]

@eversojk Since you're already editing this file, would you mind fixing the typo on line 98 (fo -> of)?

[eversojk]

Sentences marked and typo fixed!

[r-52]

LGTM

[jasnell]

Landed in 820844d