added documentation plus some cosmetic changes that make the code easier
to document