sync confusingly defines 3 types called Mutex

[huonw]

There's sync::Mutex<T>, sync::raw::Mutex and sync::mutex::Mutex. The latter two have similar signatures (no contained data) and similar but slightly different APIs. The docs don't describe the difference in detail.

This is pretty confusing (renaming and/or documenting better would be a good fix).

cc @alexcrichton

[alexcrichton]

The mutex::Mutex implementation should eventually replace the sync::raw::Mutex primitive, it just needs cvar support. After that, we're only left with sync::Mutex and raw::Mutex. I'd be a little sad if raw::Mutex were renamed to something like raw::RawMutex because raw::Mutex already conveys that information, but I can see where this may be confusing when you're searching for mutexes in the sync docs.

[sfackler]

@alexcrichton the current convention seems to be that types should be referenced without their module, so you'd actually want RawMutex. (I would also not be opposed to changing the convention, as prefixing everything is a huge pain)

[zkamsler]

It might also be worth exploring renaming Mutex<T>, as it is occasionally a source of confusion that the mutex actually contains the data that it is protecting.

[huonw]

Oh, and there's the StaticMutex type too (although this clearly has its purpose in the name, so isn't particularly confusing).

[aturon]

cc me.

[aturon]

Addressed with sync overhaul.