Add a small explanation on why Restore is needed.

[carlosalberto]

Fixes #490

cc @toumorokoshi

[toumorokoshi]

Users can rely on it to identify a wrong call order and emit a signal to warn users about the broken invariant.

Is a bit unclear to me. I'm reading between the lines, but guessing:

Wrong call order means:

because there is a pattern that an attach of a context should be paired with a detach, then someone reading the code will be able to spot the lifetime of the context. In this regard, someone can quickly identify if the context is detached in the wrong location

"emit a signal to warn users about the broken invariant" I'm having a hard time guessing. What signal is emitted? I'm assuming "broken invariant" is referring to the context object.

[carlosalberto]

@toumorokoshi Updated it to make it a little bit clearer: so basically

1. The wrong call order: trying the incorrect Context (usually not the current instance)
2. Emit a signal: either logging an error or return a value (this is implementation specific).

Let me know ;)

[carlosalberto]

Ping @toumorokoshi

[carlosalberto]

Ping @toumorokoshi Let me me know if this is better now ;)

[toumorokoshi]

I think the examples actually help the most. But either way good on merging it and not waiting for my very slow feedback :)

[carlosalberto]

@arminru Added a small note on the optional return value of the Detach Context operation. Wondering if this is enough? I know most implementations (all?) return nothing, but this way we can leave some space open for future additions ;)

[arminru]

Thanks! LGTM