add documentation and rename some variables