Improve `std::path::Path::join` documentation when path is overridden

[PitiBouchon]

On Windows, when running

path.join("C:")

the path get overridden, which is a strange behavior because Path::new("C:").is_relative() is true.

And https://doc.rust-lang.org/std/path/struct.Path.html#method.join is telling :

If path is absolute, it replaces the current path

[hanna-kruppe]

As discussed in #59726 the documentation of PathBuf::push describes this behavior. It’s only Path::join that is incomplete. It does refer to PathBuf::push, but it’s probably worth mentioning something more than “if absolute, replace current path” in join’s documentation as well.

[hanna-kruppe]

The reference to #59726 wasn't intended to imply this is a duplicate. There was earlier discussion, but discussion in #59726 has been about at least three distinct issues, which doesn't help with any of those issues getting addressed. I think it would make sense to break out an actionable issue about improving the Path::join documentation -- that could be this issue.

[PitiBouchon]

Ok then I'm leaving this issue open, specifically for this

[tusharrrr1]

The core issue is documentation clarity rather than code correctness — Windows paths have special semantics ("C:" vs. "C:\foo") that don’t fit neatly into just “absolute vs relative”.

To resolve this:

1. Improve Path::join documentation.
2. Add a code example to the docs

let me handle this if possible

[KaiTomotake]

@rustbot claim