Document everything, with examples

[kpreid]

The documentation is technically complete in the “every public item has a docstring” sense, but there are few examples of usage. The doc-tests tend to be heavy on "test" and light on "doc".

Docs/examples for specific items:

• Cell example (There is a more elaborate example in WakeFlag; make it simpler than that.)
• Cell::update_mut() example
• CellWithLocal basic usage example
• Using specific LoadStore implementations with Cell
• Constant basic usage example (barely done in 7c249ab, but could use more realism)
• Flag basic usage example
• Gate example of dynamic dependencies together with Cell, or at least some kind of switching sources
• Log basic usage example
• Notifier basic usage example (done in 67c2a9e)
• Notifier::close() usage/doctest
• Notifier::count() example demonstrating its exactness
• StoreLock basic usage example (not focusing on implementing Store)
• FromListener implementation e.g. for an enum (done in d59ce22)
• Listener implementation examples
  • Simple correct implementations
  • Tempting incorrect implementations
  • A Listener that writes to a channel — emphasize not blocking
• LoadStore implementation
• Source implementation
• Store implementation (done in e60de7d)

Examples not specific to an item:

• Usage in an event-loop-shaped application: read input, perform updates, display output.
• Usage in a reactive style application: as-needed updates in a complex graph.
• Example of using Notifier with non-type-erased listeners.
• Example of waking threads using Condvar or unpark().