reflect: improve documentation of IsNil

IsNil isn't quite the same as == nil, as this snippet shows:

// http://play.golang.org/p/huomslDZgw
package main

import "fmt"
import "reflect"

func main() {
        var i interface{}
        v := reflect.ValueOf(i)
        fmt.Println(v.IsValid(), i == nil)
        fmt.Println(v.IsNil())
}

The fact that IsNil panics if you call it with an untyped nil
was not apparent. Verbiage added for clarity.

LGTM=rsc
R=rsc
CC=golang-codereviews
https://golang.org/cl/65480043

diff --git a/src/pkg/reflect/value.go b/src/pkg/reflect/value.go
index 2490f6d13b7d5aced118932de2074c08d04745ef..1edb1f04659b340cd1c1bbcf3ae020daf3283020 100644 (file)
--- a/src/pkg/reflect/value.go
+++ b/src/pkg/reflect/value.go
@@ -1091,8 +1091,13 @@ func (v Value) InterfaceData() [2]uintptr {
        return *(*[2]uintptr)(v.ptr)
 }
 
-// IsNil returns true if v is a nil value.
-// It panics if v's Kind is not Chan, Func, Interface, Map, Ptr, or Slice.
+// IsNil reports whether its argument v is nil. The argument must be
+// a chan, func, interface, map, pointer, or slice value; if it is
+// not, IsNil panics. Note that IsNil is not always equivalent to a
+// regular comparison with nil in Go. For example, if v was created
+// by calling ValueOf with an uninitialized interface variable i,
+// i==nil will be true but v.IsNil will panic as v will be the zero
+// Value.
 func (v Value) IsNil() bool {
        k := v.kind()
        switch k {