optimisation and more documentation