#186: implemented and tested
#186: documented