adapt function and variable naming and add some documentation