code documentation, cleanup and parameterisation