- rearranged a bit to avoid duplicated information
- provide more complete (and hopefully less confusing) descriptions of
  the return values for most of these functions
  (close SF bug #563298)