migrated comments
various improvements in documentation, and updated user guide.
added two figures