add some documentation and refactorings

 * added documentation in a few spots
 * re-factored a little
 * removed warnings and deprecated calls in file common.Utilities. This does not break compatibility with older APIs