os: document behavior of IsNotExist, IsExist, etc. for nil errors

[dpinela]

The IsNotExist, IsExist, IsPermission and IsTimeout functions in package os all return false when passed a nil error, but the documentation isn't too clear about that. I presume the behavior is intentional, since there are tests for it (except for IsTimeout?). Being able to rely on this property would be nice, as it allows one to write code like the following, to treat such errors specially:

if os.IsNotExist(err) {
   // ...
} else if err != nil {
  // ...
}

I think the root of the issue is that the term "the error" in these functions' docs is ambiguous - it could mean an error value (which can be nil) or an error condition (which is represented by a non-nil error value).

[agnivade]

@ianlancetaylor

[ianlancetaylor]

The behavior is definitely intentional. I'm fine with a small documentation clarification. Maybe we could just s/this error/err/.

[seebs]

I was just about to write exactly this bug report, because I just found some code which was convoluted enough to trip up a linter because it was trying to avoid calling IsNotExist on a nil. Intuitively, I would prefer to get the false answer rather than a panic, because it is not the case that a nil is an error which represents a file not existing.

[gopherbot]

Change https://golang.org/cl/170077 mentions this issue: os: clarify that IsNotExist, IsExist, IsPermission and IsTimeout work with nil errors