add some extra docs to make things less confusing