further improvements, comments and documentation