documented the routines