intensive update of documentation and speeding up computations in some functions