revised AtomicPtr compare_and_swap wording and example

[andylamp]

The wording (and example) are quite vague; this is an attempt to clarify both the wording as well as provide a more concise example.

[tshepang]

space needed between /// and ``compare`

[brson]

This doesn't read right to me. 'the previous value contained in the pointer' sounds to me like it's not returning a pointer but a value type. 'If it is equal to the value pointed by current sounds similarly misleading. It's not actually true that if the value pointer to be current is the same as the value pointed to be the return value then the pointer was updated. What matters is the value of the pointer itself (the address). It's possible for current and new to point to two different values that are still equal - those values don't have any affect on what the CAS is doing.

[brson]

Here's my attempt.

"Stores the new pointer into the AtomicPtr if the presently contained pointer is the same as the address pointed to by the current argument.

The return value is always the previous contained pointer. If its value (the address it points to) is the same as current then the pointer was updated."

[brson]

I'd still like the wording to be refined here per my previous comments. Might also be good to have some more eyes on this, since it's hard to phrase well with the distinctions between different pointers and values being made. cc @rust-lang/libs

[alexcrichton]

Closing due to inactivity, but feel free to resubmit with comments addressed!