added more utility functions
improved documentation