more doc and fixes from jacob-carlborg