doc: path functions ignore trailing slashes

[tniessen]

Add notes about path.parse(), path.basename() and path.dirname() ignoring trailing slashes as suggested by @bnoordhuis at #6229.

Refs: #6229

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc

[bnoordhuis]

Thanks for doing this. I'd simply say "Trailing '/' characters are ignored." and leave it at that. Not everyone will be familiar with POSIX and "not counted as part of the pathname" could lead a reader to believe it's counted as part of something else; it's better to be explicit about it being ignored.

[tniessen]

@bnoordhuis You are probably right. By the way, should I add a note about Windows? Something along "Trailing '/' (and '\' on Windows) characters are ignored."?

path.posix.basename('/home/foo\\') == 'foo\\'
path.win32.basename('/home/foo\\') == 'foo'

[bnoordhuis]

Yes, a note on Windows paths would be good.

[tniessen]

@bnoordhuis Done :)

[cjihrig]

It might be best to just say "trailing slashes are ignored"

For example, path.posix.dirname('/foo/bar\\') drops the backslashes too.

[sam-github]

path.posix.dirname doesn't drop the backslashes, it considers them part of the basename:

> path.posix.dirname('/foo/bar\\') 
'/foo'
> path.posix.basename('/foo/bar\\') 
'bar\\'

Unlike Windows, which does drop them:

> path.win32.dirname('/foo/bar\\')
'/foo'
> path.win32.basename('/foo/bar\\')
'bar'
> path.win32.basename('/foo/bar\\//\\//')
'bar'

[cjihrig]

Ah, thanks.

[sam-github]

I think the wording is too subtle, its not clear enough that windows supports two dir seps, and will strip both. I would say "Trailing / characters are ignore, and on Windows trailing / and \ characters are both ignored". Or perhaps "trailing directory seperators are ignored, see REF", and explain that unix has only one directory seperator, /, but that win32 supports both / and \ (or a mixture of the two) as directory seps.

[tniessen]

How about moving the paragraph

Note: On Windows, both the forward slash (/) and backward slash (\\) characters are accepted as path delimiters; however, only the backward slash (\\) will be used in return values.

from the very bottom to the section about path.sep and referencing that section: "Trailing directory separators are ignored, see [path.sep][]"?

[sam-github]

ok. but "used in return values" means what?

> path.win32.dirname('\foo/that/bar\\//\\//')
'\foo/that'

^--- clearly / and \ are both used in return values

[tniessen]

This is preexisting (I copied that paragraph from path.md about path.win32). Is it to be considered a bug in dirname or is it a documentation inaccuracy?

[sam-github]

Looks like a doc inaccuracy to me.

[tniessen]

Just noticed that "path delimiters" is not the best wording as well, considering how path.delimiter is defined. How about

Note: On Windows, both the forward slash (/) and backward slash (\) are accepted as path segment separators; however, if separators are to be added by the Windows-specific implementations of the path methods, only the backward slash (\) will be used.

[tniessen]

@bnoordhuis @sam-github I tried to incorporate the changes discussed with Sam, thoughts on this? :)

[bnoordhuis]

I'd change the part after the semicolon to "the path methods only add backward slashes (\)."

"if ... to be ..." is probably hard to follow for people without a good command of English.

[tniessen]

Thank you, done.

[tniessen]

@bnoordhuis Would you mind reviewing my changes since your last review? :)

[benjamingr]

@bnoordhuis can you please confirm the changes performed are to your satisfaction?

[benjamingr]

Landed in 7fd2923

Thanks for the contribution!

[MylesBorins]

I've backported to v6.x. If this is inaccurate for that release please let us know