Thread safety analysis: Improve documentation for scoped capabilities

Thread safety analysis: Improve documentation for scoped capabilities

They are for more powerful than the current documentation implies, this
adds

* adopting a lock,
* deferring a lock,
* manually unlocking the scoped capability,
* relocking the scoped capability, possibly in a different mode,
* try-relocking the scoped capability.

Also there is now a generic explanation how attributes on scoped
capabilities work. There has been confusion in the past about how to
annotate them (see e.g. PR33504), hopefully this clears things up.

Reviewed By: aaron.ballman

Differential Revision: https://reviews.llvm.org/D87066