Expand documention on failures and wrapped failures types

To make it more clear why these objects and types exist and when
and why they are used and reraised increase the verbosity of the
comments and associated inline documentation on these two classes
to help explain there existence & usefulness.

Change-Id: I742bbcd69c71df80e6de7becc8aee153bf16b34b
Merge "Expand documention on failures and wrapped failures types"