further improvements of code structure and documentation