fix docs on behaviour of ~ closes #11