issue #597: added more documentation