From: Rob Pike <r@golang.org>
Date: Wed, 19 Feb 2014 06:33:59 +0000 (-0800)
Subject: reflect: improve documentation of IsNil
X-Git-Tag: go1.3beta1~661
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=8b0b994c08c540702fbfe84a50ed72b93892d7c5;p=gostls13.git

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 2490f6d13b..1edb1f0465 100644
--- 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 {