add a lot of docu and rename some vars to more speaking names