Rename one of sync::Mutex or sync::mutex::Mutex

[SimonSapin]

They currently have very different semantics: the former is a lock-protected container while the latter is only a lock. I just spent a few minutes very confused, looking at the docs for one of them to understand code using the other.

Combined with #15723 and libstd-as-a-facade (many items with the same name documented in different modules are in fact the same item), this really brings down the doc’s usability.

sync::Mutex vs sync::mutex::Mutex is just the example I hit today, but same-name-but-different items is a pattern we should avoid in general.

[thestinger]

I think using the same name for both is fine as long as the paths leading up to it make it clear that one is a low-level mutex for unsafe code and the other is a high-level abstraction.

[SimonSapin]

@thestinger, sync::Mutex vs sync::mutex::Mutex does not convey this at all, IMO. Worse, it is relatively common to reexport at the crate top-level things that are defined in modules: exactly the same naming pattern with a very different meaning.

[thestinger]

I realize that, I'm saying that it would be fine if the paths were better.

[SimonSapin]

I was gonna suggest that sync::mutex could move to sync::raw::mutex, but I just found out that sync::raw::Mutex is yet another different type…

[huonw]

#14530

[aturon]

This issue is no longer relevant after the sync overhaul.