added documentation on behaviour of functions