documentation on semantics would be good, given that negative/positive return values mean different things