review feedback.

Tweak a bunch of documentation, etc.
change the bestVersions function to not require sorted input.

The code is a trivial change, and it makes it harder to make a mistake.
If this is ever actually a performance issue, we could switch to a sorted
list that then uses bisect or whatever. But sorting the list is likely to be
the bottleneck first. (nlogn at least, rather than simply n for this one-pass
algorithm.)