updated documentation with changed semantics