In looking at another os.path.join documentation issue I tried the Windows join to see if it matched the docs, and found that it was very unclear.   I searched the tracker and found Issue 1669539, which contains much relevant discussion but also much discussion of possible enhancements.  So I'm opening a new issue *just* about what I see as the current bugs in the os.path.join docs and ntpath.join implementation.

I'm not qualified to fix this, not being a Windows user, but it is clear to me that the documentation of os.path.join for Windows is unclear (it does not indicate what is considered an absolute path on Windows) and wrong (\foo will *not* restart the path if it is the second element and follows a drive specification, but it does any other time), and that the current behavior may have a bug if, as seems to be implied by the issue 1669539 discussion, something that looks like a drive specification in the middle of a path is invalid on Windows.  If this last is not a bug, it should be mentioned in the documentation, since the actual behavior is counter-intuitive.

http://bugs.python.org/issue1669539 has been partially fixed. On Windows os.path.join('foo', 'a:bar') gives 'a:bar' not 'foo\\a:bar'. However os.path.isabs('a:bar') returns False yet it causes a reset in the join like an absolute path.

'\foo' is considered an absolute path even though calling os.path.abspath on it can yield different results - as if it were a relative path. At minimum we should amend the wording about what resets the join.

ntpath.join() was fixed in issue19456 so I think all we need here is a commit review of the attached documentation patch.

Dave, your patch is a significant improvement on the accuracy of the current doc, but the whole paragraph seems somewhat haphazard and confusing to me.  Here's my own attempt to clean it up, though I'm not certain just how much improvement it is :)

I'd say it was definitely an improvement in terms of comprehensibility.

New changeset 05274a517b37 by Zachary Ware in branch '2.7':
Issue #15414: Clean and correct the os.path.join docs.
https://hg.python.org/cpython/rev/05274a517b37

New changeset c9c6082d4f9b by Zachary Ware in branch '3.4':
Issue #15414: Clean and correct the os.path.join docs.
https://hg.python.org/cpython/rev/c9c6082d4f9b

New changeset e57f93c681a6 by Zachary Ware in branch 'default':
Closes #15414: Merge with 3.4
https://hg.python.org/cpython/rev/e57f93c681a6

Committed, with better line wrapping.

Thank you Dave Sawyer for the initial patch, and RDM for the review.