scmutil: improve documentation of revset APIs
I can never remember the differences between the various revset
APIs. I can never remember that scmutil.revrange() is the one I
want to use from user-facing commands.
Add some documentation to clarify this.
While we're here, the argument name for revrange() is changed to
"specs" because that's what it actually is.
$ hg init
$ touch unknown
$ touch a
$ hg add a
$ hg ci -m "1"
$ touch b
$ hg add b
$ hg ci -m "2"
Should show unknown
$ hg status
? unknown
$ hg revert -r 0 --all
removing b
Should show unknown and b removed
$ hg status
R b
? unknown
Should show a and unknown
$ ls
a
unknown