The "Otherwise it returns true on success, or false on failure." is implied or at least you could write that about any function. What the documentation should indicate is when failure(s) can be encountered. In this case I think what needs to be indicated is the return code is translated(y/01/10/) and passed from the underlying system call.

When a statement is always true, except for when it's false,
the cases when the statement is false _need_ to be documented.
  -- Mike Mestnik
[download]