client: xml_utils documentation update

I noticed some confusion on intended usage of some of the classes.
Added extensive documentation regarding design intent and references
to additional examples and docs.

Signed-off-by: Chris Evich <cevich@redhat.com>