add documentation, minor changes to variables and methods names