Update init/shutdown API documentation.

[hidmic]

Constrain behavior for known context states. Alternative to #242.

[ivanpauno]

is it possible to ensure that the context will remain zero initialized if rmw_init failed?

[hidmic]

I'll assume you mean rmw_init(). If we can provide an adequate return code, we can rollback what we've done and reset the content of the struct. Note this talks about the rmw_context_t struct and not about any other global state that an rmw implementation may initialize as a side effect. We can't make promises there.

[ivanpauno]

If it doesn't add much burden to the implementation, I would try to always enforce a "strong failure guarantee" (equivalent to the C++ strong exception safety guarantee), more than only a "basic failure" guarantee).

I'll assume you mean rmw_init()

Yes, edited.

Note this talks about the rmw_context_t struct and not about any other global state that an rmw implementation may initialize as a side effect

yes, there might be visible side effects that we can't control.

[hidmic]

If it doesn't add much burden to the implementation, I would try to always enforce a "strong failure guarantee"

Yeah, I know where you're going. Because I don't know for sure what is (or will be) out there, I try not to commit to more than it is strictly necessary for it not to be imprecise. In this specific case, I'd rather not make strong guarantees about anything but the struct just yet. @wjwwood for feedback.

[wjwwood]

I don't mind one way or the other. We don't usually reset structures on failure, but we do things like reclaim resources that would otherwise be leaked, which is a little more important in my opinion. The user could always re-zero init the structure if it failed. I think the only important guarantee is that no resources are leaked, so it is not needed to call shutdown or fini on it and it's say to overwrite it.

[hidmic]

Alright, going in!