also add unit tests for this function and a description into the model of the behaviour of the function