issue #612: extended documentation