[MRG] Scoring doc and tweaks

Minor usability and doc tweaks for the new scoring API.

@larsman, @arjoly, you guys would be good candidates for reviewing