To play devil's advocate (and be really nitpicky), it doesn't say "return an error" but "return on error" which does contain some useful information: That this method doesn't have any kind of sophisticated error handling but simply aborts on error.

I don't think that's very useful - you see that it doesn't have any kind of sophisticated error handling simply by looking at the method's source code (which you need to do in order to see the comment).

This is ideal, yes. Would also settle for a previous comment explaining what each int represented, if the language in question doesn't have enums.

0 and -1 as status numbers aren't that unusual to call magic.