issue #585: updated documentation