more tweaks for correctness and documentedness