updated and extended documentation of the code