gh-77607: Rephrase documentation of os.path.join()

[slateny]

https://docs.python.org/dev/library/os.path.html#os.path.join

• Issue: [doc] Behavior of os.path.join does not match documentation #77607

[slateny]

Made this part a bit more specific, but can use original suggested wording if wanted

Suggested change

	is empty, the result will end in the platform's directory separator.
	is empty, the result will end in a directory separator.

[serhiy-storchaka]

If the last member of *paths
is empty, the result will end in the platform's directory separator.

It is not true. For example, os.path.join('', '') -> ''. On Windows, os.path.join('c:', '') -> 'c:'.

[slateny]

That's a good point. Then perhaps instead, is empty, and if *path* is not a root dir or empty, then .... It can also be optionally less specific, and say, ... the result will generally end in the ....

[serhiy-storchaka]

It is problematic, because the term "root dir" needs explanation, especially on Windows.

What if just say that empty members are ignored, except the last one?

[slateny]

If it needs some explanation, then maybe we give a quick example and phrase it as "... and if path is a root directory (i.e., / or c:) or empty, then ..."

For your second statement, do you mean leaving out the note on platform separators? It seems a bit too noteworthy to leave it out though. It could be phrased differently like,

If the last element of paths is empty, the result will end in the platform's directory separator, unless path is empty or a root directory.

[serhiy-storchaka]

I afraid that it would be too verbose and still not clear. It is not good place to introduce a new term, especially if it may conflict with the meaning in other sites.

[slateny]

I see, you would prefer to keep it a bit vague, like The return value is the concatenation of *path* and any non-empty members of *paths* separated by the platform's directory separator character. Empty members of *paths* are ignored except for the last path. If a component is an absolute path, ...?

[hauntsaninja]

"end with the [...] separator" reads more naturally to me

[slateny]

@serhiy-storchaka Revisiting this, here's one alternative wording without introducing new terms:

Suggested change

	by the platform's directory separator character. If the last member of *\*paths*
	is empty, the result will end in the platform's directory separator.
	by the platform's directory separator character. If the last member of *\*paths*
	is empty, the result will usually end with the platform's directory separator.
	This does not happen in cases for certain values of *path*, such as ``'c:'``
	on Windows.

That would keep the idea of the original (but incorrect) note of the result will only end in a separator if the last part is empty. If dropping the note entirely is preferred, then I'll happily defer judgement here and in that case feel free to commit the below suggestion instead:

Suggested change

	by the platform's directory separator character. If the last member of *\*paths*
	is empty, the result will end in the platform's directory separator.
	by the platform's directory separator character. Empty members of *\*paths*
	are ignored except for the last path.

[hauntsaninja]

There was overlap (and a merge conflict) with #100783. Serhiy's feedback applies to that change as well, so I'll open a new PR to fix.