clarified/extended documentation (partially affects #265)