API Docs: sync

[steveklabnik]

Part of #29329

http://doc.rust-lang.org/std/sync/

Here's what needs to be done to close out this issue:

• the module-level documentation is very small. It should explain what the module is for in more detail, with some examples.
• std::sync::atomic could use links to the types it references.
• std::sync::atomic::fence has very... dry docs that aren't very helpful. And there's no examples.
• ATOMIC_*_INIT (link is just to BOOL but all of them) could use examples.
• Atomic* (link is to Bool but all of them) are mostly fine, but could use links to other types and some beefing up generally.
• Barrier needs a bunch of types linked.
• BarrierWaitResult should explain its relationship with Barrier and link to it.
• Condvar needs examples on its methods.
• Once needs to link to ONCE_INIT.
• PoisonError needs examples.
• RwLock needs examples, links to types, and a comparison between it and Mutex.
• WaitTimeoutResult should link to the method that creates it.
• TryLockError needs to link to the function that creates it.
• ONCE_INIT needs a link to Once and some examples.
• LockResult needs links.
• TryLockResult needs links.
• Weak could do a much better job of explaining itself.
• std::sync::mspc needs a lot of links. The docs are good but a bit jargon-heavy, expanding those would be nice.
• IntoIter needs more links and to explain how you get one.
• Iter is the same.
• Receiver needs links, examples, and more explanation of what it is.
• RecvError needs to link to recv.
• SendError needs links.
• Sender has the same issues as Receiver.
• SyncSender has the same as Sender.
• TryIter needs to link to how to create one.
• RecvTimeoutError needs to link to recv_timeout.
• TryRecvError needs to link to try_recv
• TrySendError needs to link to try_send.
• channel has almost no docs and it's the focus of this module!
• sync_channel should point to channel and then tell how it's different.

[iuliuv]

Possible inconsistency in the Rust documentation about channels:

https://doc.rust-lang.org/std/sync/mpsc/fn.sync_channel.html
Function std::sync::mpsc::sync_channel
"As with asynchronous channels, all senders will panic in send if the Receiver has been destroyed"

https://doc.rust-lang.org/std/sync/mpsc/struct.SyncSender.html
Struct std::sync::mpsc::SyncSender:
fn send(&self, t: T) -> Result<(), SendError>
"This function will never panic, but it may return Err if the Receiver has disconnected and is no longer able to receive information."

[kmcallister]

I'm working on updating the Arc docs to more closely match the refined Rc docs from #36571.

[steveklabnik]

I am happy to mentor anyone who wants to tackle this issue.

[projektir]

@steveklabnik for all the ones that need links, are you talking about for example the types wrapped in <code> tags, such as Sender under the std::sync::mpsc::Receiver page? Is it safe to say that as general rule every type under a <code> tag should link to the page for that type? Is there other linking on these pages you would expect to see?

[steveklabnik]

Is it safe to say that as general rule every type under a <code> tag should link to the page for that type?

Yes, exactly. Note that sometimes there is a bug here; that is, certain kinds of docs get rendered on two pages and so the links won't work. I don't think that's an issue here, but our tools will catch those cases, so you shouldn't worry about it too much, but figured it'd be worth a mention.

Is there other linking on these pages you would expect to see?

That's pretty much it, just the stuff that's in <code> already.

[projektir]

Someone looks to have fixed up Barrier on nightly, btw.