improve documentation + rename some parameters and a property to be clearer on their intend