update values and add documentation